Building libpcap

After a lot of false starts, it turned out to be fairly simple to build the native libpcap library. In my original attempts, I was working to build the entire Cyanogenmod ROM for my device so I could harvest the libpcap so file. While this might have eventually worked out, it was a very difficult path. In the end, the “proper” way to do this was to use the Android NDK to build the Android libpcap native code as part of my project.

Running As Root

Libpcap requires root access in order to access the low-level networking stack. On the surface, this seems pretty simple to do using the support provided by the RootTools project. However, it turns out that the combination of root applications and access to native libraries is a bit tricky.

When using RootTools, launching a root application actually involves multiple processes:

Processes Diagram

The initial process is the main application with an Android Activity. This activity interacts with the RootTools support which checks for root ability and, if found, launches a new shell process with root authority. That root shell mediates between the original Activity and root applications launched on behalf of the original activity. For short-running root applications, it is possible to communicate using the STDIN and STDOUT pipes. However, for a long-running service, it makes more sense to use some other communications channel to communicate between the Android activity and the root application. One possibility would be a Unix domain socket provided by the android.net.LocalSocket class.

Native Libraries And Root

While RootTools provides the infrastructure shown above, the problem I ran into was that when launching the root application (process 3), it would not be able to locate the native libraries that the JNI class was dependent on. The RootTools JavaCommandCapture class launches the Java class using a command similar to:

dalvikvm -cp /path/to/anbuild.dex com.android.internal.util.WithFramework com.stericson.RootTools.containers.RootClass my.package.RootCodeClass

This long incantation starts up a new Java Application using the Dalvik VM. The WithFramework class “Binds native framework methods and then invokes a main class with the remaining arguments” and then calls the RootClass class. Finally, the RootClass class invokes the RootCodeClass constructor passing along the remaining command-line arguments. RootTools expects the root functionality to occur as part of the construction of RootCodeClass, however if RootCodeClass has a JNI dependency on a native library the functionality will fail with an UnsatisfiedLinkError exception.

dalvik.system.BaseDexClassLoader

Normally, Java may be started with the “java.library.path” System property to set the location of the native libraries, however that doesn’t appear to work correctly in Android. In addition, the LD_LIBRARY_PATH from Linux won’t work either. It turns out that Android actually pulls the native library path from the Classloader that is used to load the class referring to the native static library.

The dalvik.system.BaseDexClassLoader class acts as both a Java class loader mechanism and a holder of the native library path. The initial classloader started by the Dalvik VM does not contain any references to the static library path leading to the linkage failures. I was able to solve this, by adding yet another layer of indirection:

Classloader Diagram

In this model, the initial RootCodeClass constructor creates a new BaseDexClassLoader instance referencing the native libraries path.

JavaRootClassloader targetLoader = new JavaRootClassloader(
				nativeClasspath, 
				null, 
				nativeLibPath, 
				getClass().getClassLoader());

In this case, the native classpath and native libraries have been passed in as command-line arguments from the originating Activity. The targetLoader must be used to load the target class in order for the target JNI classes to use the provided native libraries. It is important that these classes be kept in separate classloaders to avoid errors in the Dalvik VM about redefinition of classes.

Class<?>targetClass = targetLoader.loadTargetClass(targetClassName); 

The loadTargetClass method is a special Classloader method that uses classloader-first rather than parent-first lookup to avoid using the parent classloader which does not have the native library path defined.

/**
	 * Load the specified class, making sure to *not* do a parent-first load
	 * as we will end up with the wrong classloader.
	 * 
	 * @param targetClassName
	 * @return
	 * @throws ClassNotFoundException 
	 */
	public Class<?> loadTargetClass(String targetClassName) 
		throws ClassNotFoundException 
	{
        Class<?> clazz = findLoadedClass(targetClassName);

        if (clazz == null) {
        	// Look locally first for our target class
        	clazz = findClass(targetClassName);
        }

        return clazz;
	}

In the current implementation, all of the information necessary to launch the final targetted class with native library path properly set is provided by the originating Activity. Remaining command-line arguments are captured by the “launcher” class and provided as the arguments to the main method of the target class.

DEX Files

The default RootTools approach for creating Java classes that can be loaded in the root context is by adding the com.stericson.RootTools.containers.RootClass.Candidate annotation to the root classes and then processing with the com.stericson.RootTools.containers.RootClass class. The result of this process it to create an Android DEX file called anbuild.dex. I struggled to get this all to play nicely and get all of the proper classes into the proper DEX files. As mentioned, loading the same class in different classloaders can cause Dalvik VM errors that look like the following:

Class ref in pre-verified class resolved to unexpected implementation

In the end, I ended up with three separate DEX files:

• Standard application DEX file
  This file is automatically built and handled by the Android tools and the runtime. This file contains the code for the main Activity and associated logic
• Root Launcher DEX file
  This file contains just necessary classes to be loaded by RootTools and to create the special Classloader instance that can load the real root functionality while specifying the native libraries path. This DEX file is generated as rootlauncher.dex into the res/raw folder
• Root functionality DEX file
  This DEX file contains the Java functionality that will run in a root context that will have access to the native libraries necessary to interact with the system. This DEX file is generated as root.dex into the res/raw folder

Building The DEX Files

Because of this added complexity in creating the multiple DEX files, I had to take more control over the build process. Taking advantage of Eclipse’s ability to call out to an Ant build.xml as part of the build process. For instance, the build.xml file for generating the DEX files would look something like:

    <target name="build_root_dexs">  	
    	<property name="dx.path" value="${user.home}/software/unzipped/android-sdk-macosx-personal/build-tools/${build-tools-version}/dx" />
    	
    	<!-- Build the root launcher -->
    	<unzip src="libs/RootTools-3.3.jar" dest="bin/classes-launcher">
    		<patternset>
    			<include name="com/stericson/RootTools/containers/*.class"/>
    		</patternset>
    	</unzip>

    	<echo message="Building rootlauncher.dex" />
    	<exec executable="${dx.path}">
    		<arg value="--dex" />
    		<arg value="--output=res/raw/rootlauncher.dex" />
    		<arg value="--positions=lines" />
    		<arg value="bin/classes-launcher" />
    	</exec>
    	
    	<!-- Build the code that will run within the root container -->
    	<echo message="Building root.dex" />
    	<exec executable="${dx.path}">
    		<arg value="--dex" />
    		<arg value="--output=res/raw/root.dex" />
    		<arg value="--positions=lines" />
    		<arg value="bin/classes-root" />
    	</exec>
  </target>

An Ant build can be added to the build file via the Project properties:

Eclipse Builders

Add a new Ant Builder:

Eclipse Builder Type

Choose your Ant file:

Ant Build File

And save the resulting build launch configuration:

Build Configuration

Caveats

While this approach is working fine for Android 4.0+, there are a lot of pieces of this puzzle that are private/internal to the Android implementation. For that reason, many of these internals have the chance of changing over time. In particular:

• The com.android.internal.util.WithFramework is clearly marked as an internal class
• The dalvik.system.BaseDexClassLoader is yet another internal class that may disappear or change
• Even the Dalvik VM will likely go away in the future and be replaced by the new Android ART runtime

The best way to debug your Android modules right now is a bit old fashioned. When there is a problem or unexpected behavior in your module, use log statements to trace through your code’s execution.

However, the functionality I was working on was complicated enough that I needed the comfort of Eclipse step-debugging to truly feel like I was able to see what was going on inside my code. With that in mind, I dug around and figured out a way to debug these native modules and discovered some cool functionality in the Android Debug Bridge (adb) that I was previously unaware of.

Native Module Creation

The module creation and implementation steps are no different than the standard steps documented by Appcelerator. Once that is complete and it is time to do some debugging, I found the following to work to allow for step-wise debugging of the module. (NOTE: This has only been attempted on-device, although I expect it should work on top of the Android emulator).

Setting Up Module Debugging

After making testable changes, execute the “install” target of the build.xml file for your module to get the module properly installed on the device. At this point, it is necessary to enable debugging of your module’s example application if it has not already been handled via the Android manifest file. The basic command looks like:

adb shell am set-debug-app -w –persistent my.package.name

Where the two options can be used dependent on your needs:

• -w
  Wait for debugger at start. Use this if you need to debug something that starts early in the module’s startup routines
• –persistent
  Remember that this application should be debuggable across reinstalls.

With a debuggable application, it is actually possible to use the application’s process identifier to connect up a local port to the application’s JDWP agent. For instance, if you look at the output of “ps” from the shell, you will see something like the following:

USER PID PPID VSIZE RSS WCHAN PC NAME
…..
u0_a48 1471 795 215984 29516 ffffffff b7e62157 S com.seterasoft.sync.scheduler
…..

With this knowledge, adb can be used to forward host traffic from TCP port 9999 to the JDWP agent for this particular process using this command:

adb forward tcp:9999 jdwp:1471

Given my infinite laziness, I prefer to do this linkage with a script to avoid manual steps as much as possible. Thus, I created this simple Groovy script to query for “my.package.name” and link it to local TCP port 9999.

#!/usr/bin/env groovy

def ps = "adb shell ps".execute().text
def reader = new StringReader(ps)

def found = false
reader.eachLine { line ->
    if (line =~ /my\.package\.name/) {
    	found = true
        def pid = line.split()[1]
        println "Forwarding tcp:9999 => jdwp:${pid}"
        println "adb forward tcp:9999 jdwp:${pid}".execute().text
    }
}

if (!found) {
	println "Did not find application process.  Is it running?"
}

It is important to understand that this linkage must be re-established each time that the application is rebuilt and/or redeployed. This will result in a new process being started and a new ADB forward must then be configured.

Debug with Eclipse Remote Debugger

With debugging enabled for the application and a JDWP forwarding set up via ADB, it is just a matter of using the standard Eclipse remote debugging configuration. Assuming the previously documented forwarding set up, Eclipse remote debugging can be configured to debug via local port 9999 and ADB will proxy those requests to the running (or waiting) application.

While this requires a bit more setup than some standard debugging and only works for Android, I’ve still found it well worth the time and effort while working on native modules for Android in Titanium.

adb shell dumpsys > /path/to/dumpsys.txt

will collect the output of the dumpsys command run on the connected device into the specified file. Looking in the output from dumpsys the LocationManagerService dumps into a section

DUMP OF SERVICE location:

Within that section, there are a number of LocationListeners that look something like

Receiver{419e7ad0 Listener android.os.BinderProxy@41b8abd0}mUpdateRecords: {passive=UpdateRecord{421e75a0 mProvider: passive mUid: 10084}}:
passive:
UpdateRecord{421e75a0 mProvider: passive mUid: 10084}
mProvider=passive mReceiver=Receiver{419e7ad0 Listener android.os.BinderProxy@41b8abd0}mUpdateRecords: {passive=UpdateRecord{421e75a0 mProvider: passive mUid: 10084}}
mMinTime=0 mMinDistance=0.0
mSingleShot=false
mUid=10084
mLastFixBroadcast:
mProvider=network mTime=1346849822124
mLatitude=44.0836108 mLongitude=-92.5067299
mHasAltitude=false mAltitude=0.0
mHasSpeed=false mSpeed=0.0
mHasBearing=false mBearing=0.0
mHasAccuracy=true mAccuracy=20.0
mExtras=Bundle[mParcelledData.dataSize=148]
mLastStatusBroadcast=0

This UpdateRecord is particularly bad because it is requesting constant updates:

mMinTime=0 mMinDistance=0.0

The mUid specifies the process identifier requesting the updates. The processes are dumped within the same output and can be found in the section beginning:

ACTIVITY MANAGER RUNNING PROCESSES (dumpsys activity processes)

Each application is listed separately by process identifier:

*APP* UID 10084 ProcessRecord{41af23e8 13037:com.google.android.apps.maps:LocationFriendService/10084}
class=com.google.googlenav.android.AndroidGmmApplication
dir=/data/app/com.google.android.apps.maps-1.apk publicDir=/data/app/com.google.android.apps.maps-1.apk data=/data/data/com.google.android.apps.maps
packageList=[com.google.android.apps.maps]
compat={240dpi always-compat}
thread=android.app.ApplicationThreadProxy@42457df0 curReceiver=null
pid=13037 starting=false lastPss=0
lastActivityTime=-6m23s226ms lruWeight=-50901 serviceb=false keeping=false hidden=true empty=true
oom: max=15 hidden=12 curRaw=12 setRaw=12 cur=12 set=12
curSchedGroup=1 setSchedGroup=1 systemNoUi=false trimMemoryLevel=0
hasShownUi=false pendingUiClean=false hasAboveClient=false
setIsForeground=false foregroundServices=false forcingToForeground=null
persistent=false removed=false
adjSeq=3891 lruSeq=535
lastWakeTime=0 time used=0
lastCpuTime=20 time used=+20ms
lastRequestedGc=-6m28s504ms lastLowMemory=-6m28s504ms reportLowMemory=false
conProviders={ContentProviderRecord{418add48 com.android.providers.settings.SettingsProvider}=1}
receivers=[ReceiverList{41a84148 13037 com.google.android.apps.maps:LocationFriendService/10084 remote:41a83f70}]

With this information we have our culprit. Process identifier 10084 is Google’s LocationFriendService (Latitude). This process is requesting constant location updates and causing severe battery drain. In this particular case, I was able to go through the Latitude settings and disable everything related to location updates. With those settings disabled and a quick restart, my battery drain went back to normal again. Hopefully this information may be helpful to others having battery drain issues related to location updated.

Depending on the device and operating system level, there are subtle changes in behavior. In most cases, there is a crash log written to the /data/tombstones folder. The most revealing tombstone file has come from a Samsung Captivate running a version of the AOKP ICS ROM.

Build fingerprint: 'samsung/SGH-I897/SGH-I897:2.3.5/GINGERBREAD/UCKK4:user/release-keys'
pid: 1758, tid: 1777  >>> com.seterasoft.mclock <<<
signal 11 (SIGSEGV), code 1 (SEGV_MAPERR), fault addr deadbaad
 r0 deadbaad  r1 00000001  r2 40000000  r3 00000000
 r4 00000000  r5 00000027  r6 50c53b40  r7 00000064
 r8 41338018  r9 00000024  10 50c53a6c  fp 50c53ab0
 ip ffffffff  sp 50c53a30  lr 400fdf79  pc 400fa694  cpsr 60000030
 d0  0000000000000000  d1  0000000000000000
 d2  0000000000000000  d3  0000000000000000
 d4  0000000000000000  d5  0000000000000000
 d6  0000000000000000  d7  0000000000000000
 d8  0000000000000000  d9  0000000000000000
 d10 0000000000000000  d11 0000000000000000
 d12 0000000000000000  d13 0000000000000000
 d14 0000000000000000  d15 0000000000000000
 d16 0000000000000000  d17 0000000000000000
 d18 0000000000000000  d19 0000000000000000
 d20 0000000000000000  d21 0000000000000000
 d22 0000000000000000  d23 0000000000000000
 d24 0000000000000000  d25 0000000000000000
 d26 0000000000000000  d27 0000000000000000
 d28 0100010001000100  d29 0100010001000100
 d30 0000000000000000  d31 3ff0000000000000
 scr 2800001b

         #00  pc 00017694  /system/lib/libc.so
         #01  pc 00007bb0  /system/lib/libcutils.so (mspace_merge_objects)
         #02  pc 0007b6c8  /system/lib/libdvm.so (_Z21dvmHeapSourceFreeListjPPv)
         #03  pc 00042ce0  /system/lib/libdvm.so
         #04  pc 00032f94  /system/lib/libdvm.so (_Z22dvmHeapBitmapSweepWalkPK10HeapBitmapS1_jjPFvjPPvS2_ES2_)
         #05  pc 00042c9c  /system/lib/libdvm.so (_Z27dvmHeapSweepUnmarkedObjectsbbPjS_)
         #06  pc 000337c0  /system/lib/libdvm.so (_Z25dvmCollectGarbageInternalPK6GcSpec)
         #07  pc 0005ff6c  /system/lib/libdvm.so (_Z17dvmCollectGarbagev)
         #08  pc 00072a8e  /system/lib/libdvm.so
         #09  pc 00030a8c  /system/lib/libdvm.so
         #10  pc 00034248  /system/lib/libdvm.so (_Z12dvmInterpretP6ThreadPK6MethodP6JValue)
         #11  pc 0006c692  /system/lib/libdvm.so (_Z14dvmCallMethodVP6ThreadPK6MethodP6ObjectbP6JValueSt9__va_list)
         #12  pc 0006c6b4  /system/lib/libdvm.so (_Z13dvmCallMethodP6ThreadPK6MethodP6ObjectP6JValuez)
         #13  pc 0005f7c0  /system/lib/libdvm.so
         #14  pc 00012c14  /system/lib/libc.so (__thread_entry)
         #15  pc 00012744  /system/lib/libc.so (pthread_create)

The failing function appears to be implemented in dlmalloc.c in the Android source, but I really don't have any good idea about what might be causing the crash. I also don't appear to be the only one, as there are other references on the web that look similar.

To this point, I've tried a variety of things to try to track down the problem. I've gone so far as to try to build my own version of the Cyanogenmod with the idea that I might be able to add more logging output. So far, I've not had any luck with this approach. I generally have no problem walking away from hobby projects when I lose interest. However, this has turned into a competition of me versus the computer and I'm not quite ready to give up.

Parsing and rendering the various SVG layers that make up each clock is a relatively expensive operation. Locking up the user interface while doing these operations is bad design and leads the user to believe that the application may not working correctly. What I’m attempting to do seems pretty simple on the surface. The following screen capture shows the (partially working) goal:

The selector consists of two columns, an image of the clock on the left and the name of the clock on the right. Using the standard ListActivity support, the goal is to show an indeterminate progress image in the left column until the layers have been loaded and rendered. At that point, the animated progress image is hidden and the clock image is displayed.

The implementation is simple in concept. The list adapter subclasses the standard BaseAdapter implementation to provide an implementation of the getView method. The getView method delegates loading of the clock’s image to an asynchronous task, keeping the user interface alive. When the asynchronous task completes, it signals the adapter by calling notifyDataSetChanged. The next call to getView will hide the progress animation and display the rendered image.

While this is mostly working, I’m hitting a random deadlock condition that locks up the UI thread, usually resulting in an “Application Not Responding” (ANR) error message to the user. All of my attempts to diagnose and resolve this issue have ended with nothing but frustration. So far, I’ve tried all of the “standard” approaches to diagnose this:

• Analyzed the traces.txt file generated by the ANR.
  Unfortunately, the process never shows up in the log file.
• Force-generated a traces.txt file using kill SIGQUIT pid while the application was still running.
  Again, the process doesn’t seem to show up. Instead, I see “W/dalvikvm(19144): threadid=4: spin on suspend #1 threadid=9 (pcf=0)” whenever attempting this.
• Attempted to use the standard Eclipse debugger to suspend the UI thread once it is locked up.
  No big surprise that it did not work.
• Added lots of Log output trying to pinpoint the hang.
  At least from that logging, it doesn’t appear to be a hang anywhere directly in my code.
• I even tried to use method tracing to see if I could figure anything out.

At this point, I’ve run out of good ideas on how to track down and fix this problem on my own. I’ve gone ahead and joined the Google android-developers group and asked for ideas on solving this. I’m still waiting for my question to clear moderation to see if anyone else can offer any insights. If anyone reading this has any ideas, I’d love to hear them. Until then, this project is officially deadlocked.

The internet offered no examples of how I might go about doing this, so I went spelunking on my own. For those that may need to do something similar, I decided to capture the steps I used to relink my Android Market applications with a single GMail address. Before I go any further, let me offer some warnings:

November 13, 2011 Update

While this appears to work in the short term, I’m noticing applications slowly migrating back to the original accounts. I’m not entirely sure where those values are being stored or how to fix this permanently.

The Market Assets Database

As of this writing, Android Market (implemented by the com.android.vending package) stores the linkage between an Android application package and the associated Android Market account in the file:

/data/data/com.android.vending/databases/market_assets.db

The ASSETS table within that SQLITE database contains the mappings as seen in this screenshot.

Relinking applications is a matter of properly updating this table. The prerequisites for this process are:

• Rooted device
• Android Debug Tools (adb) installed and working

Relinking Process

Start by making sure that Market application has been stopped:

1. Navigate to Settings -> Applications -> Manage Applications
2. Locate and select the Market application in the list
3. Press the Force Stop button

Make sure that your device is attached with USB Debugging enabled:

$ -> adb devices
List of devices attached 
3231174E43AA00EC	device

Open a shell on the device and navigate to the database directory:

$ -> adb shell
# cd /data/data/com.android.vending/databases
# ls -l
-rw-rw----    1 app_57   app_57       34816 Oct 29 11:55 market_assets.db

Backup the current file:

# cp market_assets.db market_assets.db.save
# ls -l
-rw-rw----    1 app_57   app_57       34816 Oct 29 11:55 market_assets.db
-rw-rw----    1 root     root         31744 Oct 29 11:44 market_assets.db.save

Update the database file:

# sqlite3 market_asset.db
sqlite> update ASSETS set ACCOUNT = 'new.email@gmail.com' 
   ...> where ACCOUNT = 'old.email@gmail.com';
sqlite> .exit
# exit

At this point, reboot your phone. If all went correctly, your free applications should now be associated with new.email@gmail.com.

Updating Paid Applications

As I mentioned earlier, this process can’t be used to relink paid applications due to DRM that is tied to your account. If you want to do this, most application developers will offer a refund if you purchase on a new account and send them the order details for both the old and new accounts. Once you’ve purchased on the new account, you can uninstall for the old account and reinstall from the new. This is a lot of effort, but can help if you need to switch market accounts.

This screen capture from the emulator shows multiple live instances of the widget running simultaneously with many different themes. I would not suggest that anyone actually do this do the amount of memory required, however it shows the power of the themes.

Android analog clock displaying many themes simultaneously.

Implementation Notes

Getting to this point has been an interesting process, as the Android widget support definitely makes this type of widget somewhat difficult to build.

AndEngine SVG Support

I’ve had this idea for quite some time. What helped me move forward was the addition of SVG support to AndEngine. Thanks to Nicolas Gramlich yet again for his excellent engine. I’ve found a few glitches along the way that I’ve started to submit patches to the project to correct, but as always his code works amazingly well.

Per-Minute Updates

As I mentioned in my inertia post, the standard Android widgets model is really more of a “pull” model versus a “push” model. The widget provider definition file (in XML) specifies the frequency that the Android framework will call the widget’s update functionality:

    android:updatePeriodMillis="1800000"

However, no matter what is specified for this value, Android limits the update frequency to no more than once every 30 minutes to avoid the battery drain associated with executing code too often. Thus, it is necessary to push changes to the widget based on our own schedule to make sure the clock is updated every minute.

My initial implementation used Java’s Timer and TimerTask to do these updates. Looking at the framework’s analog clock implementation, I discovered Android’s time-related broadcast messages:

• Intent.ACTION_TIME_TICK
• Intent.ACTION_TIME_CHANGED
• Intent.ACTION_TIMEZONE_CHANGED

Using these broadcast messages is a vast improvement over maintaining my own timer threads for this functionality. However, since a widget is nothing more than a fancy broadcast receiver, it is necessary to spin up a separate service to register a broadcast receiver for these messages. On reception of one of these messages, each clock instance is updated to match the current time. This update generates a properly sized bitmap that is pushed to the widget instance:

		RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.main);
		views.setImageViewBitmap(R.id.imageview, bitmap);
		appWidgetManager.updateAppWidget(instanceIdentifier, views);

It’s important to note that there is also an updateAppWidget method call that accepts an instance of android.content.ComponentName. Using this method will update all instances for the specified provider with the bitmap. It took a bit to figure out why all of my clock instances were showing the same theme until I realized it was due to using the wrong method.

Improving Battery Performance

Given that this widget is controlling updates rather than allowing the framework to do the job, my primary concern is in terms of performance. Android devices are notorious for poor battery life, however it does seem that it is primarily due to background applications. I’ve done a couple of things thus far to attempt to minimize battery usage.

No Seconds Hand

At least at the moment, the widget removes the seconds hand to avoid pushing more updates to the screen than necessary. Assuming that Android wants to limit updates to once every 30 minutes, the widget is already pushing updates 30 times more often than the framework would like. Multiplying that yet again by 60 seconds seems like a bit too much. In the future, I may consider allowing the user to enable the seconds hands with proper warnings attached.

Manage Broadcast Receiver Messages

An unfortunate side effect of the way that widgets work is that it does not appear to be possible for a widget to determine if it is actually being displayed. If a widget is placed on screen 1, but the user is currently viewing screen 2, there is really no reason to update the widget. With that said, the implementation can still be smart about updates. The service alters the messages it listens for based on the status of the screen:

• Screen Off
• Intent.ACTION_USER_PRESENT
• Screen On
• Intent.ACTION_SCREEN_OFF
• Intent.ACTION_TIME_TICK
• Intent.ACTION_TIME_CHANGED
• Intent.ACTION_TIMEZONE_CHANGED

After the user has cleared the lock screen (ACTION_USER_PRESENT), the widget registers to hear time updates as well as the screen turning off. Once the screen turns off, the widget stops listening for time updates and switches to listening for user presence. This lowers the update frequency for the widgets when there is no chance that they will actually be visible to the user.

What’s Next?

This project has a chance of being something that I can complete and that others might be interested in actually using. I’m considering whether I want to submit this to the Android Market when it is a bit further along. If I do, I will have to decide whether or not I would charge for it which implies a certain level of required support. Either way, I’m not at the point of releasing any significant amount of source code until I decide what to do with this project.

Inertia is the resistance of any physical object to a change in its state of motion or rest, or the tendency of an object to resist any change in its motion.

For me, this also describes my tendencies toward side projects like my Pingus project. When I last worked on Pingus a couple of months ago, I updated the underlying AndEngine libraries and found a ton of breaking changes. I put Pingus on the shelf until I had more time to look at the breakage and how to solve it. The AndEngine changes are pretty significant and I’m going to need to rethink portions of Pingus in order to get things running correctly again.

Now my personal inertia is kicking in and causing me to put off this rework for a while. To me, this is the biggest difference between work and hobby projects… I don’t have to work on hobby projects if I don’t want to. Thus, Pingus is “on a break” for a while until I find the energy to bring it up to date relative to the underlying game engine.

In the meantime, I decided I wanted to spend a bit of time taking a look at Android’s App Widget support. Until I started digging into the documentation and examples, I had always assumed that a widget was provided a Canvas to draw directly on to the home screen. To me this seemed like it would have been the easiest way for developers to develop widgets.

It turns out that Android AppWidgets don’t work that way at all. AppWidgets are built on top of Remote Views. According to the Android documentation, Remote Views are

A class that describes a view hierarchy that can be displayed in another process. The hierarchy is inflated from a layout resource file, and this class provides some basic operations for modifying the content of the inflated hierarchy.

A Remote View is created in one process and passed into the process that owns the Android home screen. It is actually a Parcelable object, however due to class loading issues, there is only a very small number of Views and Widgets that are allowed to be passed across the process boundary. For anything that involves relatively complex graphical rendering, the only real way to drive the widget’s contents is by specifying a very simple widget layout:

and then sending bitmaps to the image view:

	private void updateWidget(Context context, AppWidgetManager appWidgetManager) {
		Bitmap bitmap = Bitmap.createBitmap(100, 100, Config.ARGB_8888);
		Canvas canvas = new Canvas(bitmap);
		
		this.drawable.draw(canvas);

		RemoteViews views = new RemoteViews(context.getPackageName(), R.layout.main);
		views.setImageViewBitmap(R.id.imageview, bitmap);

		ComponentName componentName = new ComponentName(context, MyAppWidgetProvider.class);
		appWidgetManager.updateAppWidget(componentName, views);
	}

While this seems like a high overhead way to handle updates to the widget contents, I have to assume that the Android developers had a good reason for doing things like this. I can only hope that there are some tricks being done in the Android implementation that lower the cost of this operation. Given that I’ve just managed to get this to work at all, I imagine there are is a lot of room for improvement in my use of this API. However, I found it confusing enough to figure out how to do and thought others might benefit from my pain.

In reading the Android supports-screen documentation, it is clear that it is necessary to set the xlargeScreens attribute to true. However, the xlargeScreens attribute is not supported below API level 9. Trying to shoehorn that attribute into my project that was attempting to support back to API level 5, resulted in the following error.

XLargeScreens Attribute Failure

With a bit of finagling, I was able to get things working. In order to allow the xlargeScreens attribute, it is necessary to specify a target SDK version of at least 9.

XLargeScreens Working

This screenshot shows how the minimum SDK version can be set below version 9 and the target version is set to 9, allowing the xlargeScreens attribute to be specified. In addition, it is necessary to change the Android version level in the project properties.

XLargeScreens Properties

With the project properties set to use API level 9 there does not appear to be any automated way to restrict access to API that was older than version 9. Because of this, I do worry about choosing Android API’s that will not work at the minimum SDK and will fail on-device. My plan at this point is to switch back to building primarily for low end and switch once in a while to try on my Xoom. If I were a bit more serious, I would probably handle this automatically as part of a build script.

I do wish that Google had handled things differently in regard to how this works.