Resources | developer.brewmp.com Resources | developer.brewmp.com

Developer

resources

IShell and IEnv

For every loaded and initialized Brew MP module, an IShell or IEnv pointer is passed to module code when its classes are instantiated.

Class inheritance from BREW

Brew MP incorporates the BREW Application Framework, which provides a runtime environment for Brew MP applications. Applets run in Brew MP within the environment created by the application framework. Each environment scope is identified by an instance of the shell. The application framework provides applications with an instance of the shell interface (IShell). Shell coordinates applets at runtime by providing them with a method to create instances of classes by ID. The application framework also serves applets with a set of utilities in AEEStdLib.h.

Most IShell-based classes in Brew MP were inherited from the BREW platform. In BREW there is no clear separation between application framework and platform services. There is only one shared execution environment and memory domain for the platform services. Some of these classes also made the following assumptions:

  • The main goal for these programs is to provide API services for direct consumption by applets or indirect consumption by another IShell-based program. Some of these programs are strictly for direct use by applets, and the implementation requires that the user of the program be capable of receiving events on IApplet_HandleEvent(). Examples are deprecated controls such as text, menu, etc.
  • Objects in these programs were created by the shell instance, so they always had access to pointer to IShell. The implementation had heavy dependency on the shell, application local storage (or application globals), and interfaces in AEEStdLib.h.
  • They typically run in the single designated BREW thread in the system.

A few other program types belong to one of the above categories. They may also support a contract needed by a particular framework. Some popular ones are the following:

  • Applets are IShell-based programs that implement the IApplet interface. These programs typically incorporate a user interface and are visible to the user in the application launcher.
  • Notifiers are the IShell-based programs that implement the INotifier interface. Applets typically subscribe to notifiers to receive notifications. The BREW application framework mediates the subscription and notification operations between notifiers and applets.

IShell

An IShell object is the first object provided to each class when created in a MOD file. All classes created in MOD are by default IShell-based classes. A class (or any class it uses) that has access to an IShell object is instantiated and used inside the BREW Shell, and has an IShell dependency. The IShell object is always available, exposes objects and services provided by the BREW Shell, and can be used to discover and create other objects available in the system. It can discover and create any other object in the system via IShell and IEnv.

An IShell-based class is defined as a class that is given the IShell object when instantiated. This can be observed by examining whether an IShell pointer is passed to the class by the system via the constructor or the new function of your class. For example:

int AEEClsCreateInstance(AEECLSID ClsId, IShell *pIShell, 
               IModule *po, void **ppObj)

IShell-based classes exhibit the following characteristics:

  • Single-threaded implementation
  • BREW Shell is used, with interface IShell
  • Only used within the execution environment provided by the BREW application framework
  • Cannot be used as a service class

IEnv

An IEnv object is the first object provided to each class created in a MOD1 file. An IEnv object exposes services provided by Env, such as class discovery, instantiation, and memory allocation.

An IEnv-based class is defined as a class that was given an IEnv object when instantiated. This can be observed by examining whether an IEnv pointer is passed to the class by the system via the constructor or the new function of your class. For example:

int c_basicmod1app_New( IEnv* piEnv, AEECLSID cls, void** ppif)

Each object in Brew MP resides in an IEnv and has access to an IEnv object If it has no IShell dependency, it can be instantiated and used inside as well as outside the BREW Shell. If instantiated inside the BREW Shell, it can discover and create any other object in the system via IShell and IEnv. An IShell object can be derived via IEnv.

If instantiated outside the BREW Shell, the IEnv object can be used to discover and create other IEnv-based objects that don't have an IShell dependency. It can be multi-threaded when instantiated outside the BREW Shell. Some Brew MP APIs and all the classes in MOD1 are IEnv classes.

IEnv-based classes that have IShell dependency have all of the same characteristics of IShell-based classes discussed previously. IEnv-based classes without IShell dependency exhibit the following characteristics:

  • Can be a service class
  • Can contain multi-threaded implementation
  • Free of BREW Shell
  • Can be used inside or outside the execution environment provided by the BREW application framework.

For more information on IEnv, see the Memory and Heap Technology Guide for Developers, in http://developer.brewmp.com/resources on the Brew MP website.

The following diagram shows how both IShell and IEnv manifest in runtime memory.