xtensions are tricky objects. They behave similarly to C++ classes except they're ruthlessly complicated to implement. They give Brew developers, usually limited to C code, a chance to stretch their legs into the wonderful world of objects and obfuscation. Extensions, when mastered, give nearly all the benefits of C++ style with a few drawbacks. In this article, I hope to do three things:
- I will bore you, at length, with an explanation of Brew's extension architecture.
- I will demonstrate how to create, use and destroy a custom Brew extension.
- I will explain how to take advantage of C++ code from within a C only extension.
I've written a very simple object that reverses strings for the purpose of demonstration. It's not a particularly useful or complicated object, but it should serve to demonstrate the topic at hand. Hopefully, you'll finish with a strong understanding of Brew's extensions and the experience to put that architecture to work in your own projects.
Extensions in Context
Before diving into the nuts and bolts, let's quickly discuss how Brew extensions function from a somewhat academic standpoint. If you're reading this article for more practical purposes, feel free to skip down to the next section.
In a single sentence, Brew extensions can be described as macro-accessed virtual tables.
Let's break that down a little. At the heart of each extension lies a structure containing a series of function pointers. Here's an example from the IReversal header file:
uint32 (*fnRelease)(IReversalCls *pIRevCls);
uint32 (*fnAddRef)(IReversalCls *pIRevCls);
uint32 (*fnSetString)(IReversalCls *pIRevCls, char *szStringData);
uint32 (*fnGetString)(IReversalCls *pIRevCls, char **ppszResult);
uint32 (*fnGetWideString)(IReversalCls *pIRevCls, AECHAR **ppszResult);
typedef struct IReversalClsVtbl IReversalClsVtbl;
In the above code, you can see that the structure contains a pointer to all the functions I'll be fleshing out later in the extension. It is allocated and filled in at run-time to contain the addresses for every method in the object. To the public world outside the extension, the object appears to contain nothing more than the aforementioned table. In fact, here's the public declaration for the IReversal
extension also from IReversal.h
struct IReversalClsVtbl *pvt;
typedef struct _IReversalCls IReversalCls;
This simple one item structure is the public interface object that gives the rest of the applications on the phone access to your methods. It should be noted that the structure of this extension is slightly out-dated. It is possible to use AEEVTBL
and other macros, provided by Qualcomm, to handle some of this busy work. For the purposes of clarity and ease of explanation, I'll use the older technique. Here's the internal version of the IReversal
typedef struct _IReversal IReversal;
//VTable must be the first member of the structure
To cast the external object to the internal one without crashing the handset, the public structure must be a subset of the private one. This means the vTable
must be the first element in every extension. Once that first entry is out of the way, the order of the other elements doesn't matter. Any number of private data types can follow.
Macros, published in the public header, reference the members of the vtable structure you saw earlier. Those references allow the rest of the world access to your extension. Because the above examples and explanation could be a little confusing, perhaps an example from the Brew API will better illustrate the point. For instance, Brew's IDisplay extension is one of most important extensions a mobile engineer will interact with. It handles most of the display rendering done on the screen.
What exactly happens when someone calls IDISPLAY_Release? IDISPLAY_Release is a macro with the following definition:
#define IDISPLAY_Release(p) AEEGETPVTBL(p,IDisplay)->Release(p)
This macro identifies a memory location. At the end of that pointer, the compiler will find the location of the "Release" function for the IDisplay
object in memory, just as it would in the IReversal
object. Runtime then jumps to that address in memory and executes. Ever wonder why the phone will crash and burn if you call IDISPLAY_Release
on a null or junk pointer? The program executes from an off-set of address 0
. This causes the stack to jump to an illegal location in the heap, hence the "Memory Access Error" crash that Brew programmers have come to hate so much.
From a practical standpoint, these custom extensions can be used anywhere that it would make sense to use a C++ class. Due to their complexity, programmers on a deadline tend to shy away from building generic extensions. This is a shame, as they allow for easy extensibility, reliability, portability, and obfuscation. Any extension you write for yourself can be easily packaged up and licensed to another company, another department, or given to your co-workers with a simple and easy interface. Again, Brew extensions have functionality nearly identical to a C++ class full of virtual functions. Almost any argument for the class is an argument for Brew extensions. Brew's API is also a series of extensions; if you follow the directions laid out in this article, you can write an object to extend the functionality of a Brew object.