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

Developer

resources

Classes

In Brew MP, software programs are written as classes. A class is a user-defined type that encapsulates data and behavior (functions) to provide implementation of one or more interfaces it exposes. Classes are identified by unique 32-bit AEECLSIDs. The AEECLSIDs supported for a module are specified in the module's CIF/MIF. When a class is instantiated, it becomes an object, which is an instance of the class in memory that maintains the data members of the class and the VTable to the code of all its supported methods. The vtable contains the addresses of the functions provided by the class.

C/C++ programs in Brew MP implement three types of Brew MP classes:

  • Applet classes
  • In-process classes
  • Service classes

In-process and service classes are non-applet classes, and have some similar behaviors. Non-applet classes are instantiated using a unique ClassID via IEnv_CreateInstance(), or IShell_CreateInstance() if the caller has access to IShell. Non-applet classes are released via the Release() method exposed by the classes. When a non-applet class is instantiated, the default interface is returned to the caller and the caller can use the QueryInterface() method exposed by the class to discover other interfaces supported by the class.

The table below describes the module formats and types, and wizards for these classes.

Brew MP class types Supporting module formats Applicable Brew MP module types Supporting IDE Wizards
Applet class MOD or MOD1 Application Application (applet class)
In-Process class MOD or MOD1 Application or extension Extension (in-process class)
Service Class MOD1 Application or extension through Add->Class->Service Class

In the figure below, the interface name is example_IFoo, and the instantiated class (object) is CExample. As shown below, there can be multiple instances of the same class. Every CExample object has a pointer to the vtable and a reference count that keeps track of the number of references to the interface.

A component can have multiple interfaces, each of which provides a different functionality set for clients with different roles. Multiple interfaces allow multiple references to multiple vtables, each of which provides different functionality. All references to the same interface point to the same vtable, which is in the same area of memory, and is therefore the same code.

Since clients receive and operate on a reference (the address of a pointer to the interface), developers can dynamically cast that pointer type. It is common practice to have a "smart" pointer to the actual instance. In the figure below, example_IFoo creates an instance of CExample and locally stores pvt (the pointer to the Vtable). The second field stores me, which is a pointer to the actual instance of CExample.

Typically, a class can contain one or more interfaces. See Interfaces for more information.

There are two commonly used mechanisms for creating instances of a class with QCM interfaces.

  1. Using the IShell_CreateInstance() or IEnv_CreateInstance(). Classes with QCM interfaces may register (or advertise) in the CIF/MIF. These classes are typically identified by 32 bit unique identifiers referred as ClassIDs. Instantiation of these classes is done using IEnv_CreateInstance(), or IShell_CreateInstance() if the class has access to the IShell object. In the following example, AEECLSID_CallMgr represents a ClassID of the call manager class.

    IEnv_CreateInstance(piEnv, AEECLSID_CallMgr, (void**)&piCallMgr)
    // returns an instance of call manager class in piCallMgr

  2. Using a factory class. These classes have interfaces that output instances of another class. A factory class is typically used to express the additional initialization parameters to make an object. The following example returns an instance of class Call, initialized to its originating state with the listener and destination phone number.

    ICallMgr_OriginateVoice(piCallMgr, "8585555555", piListener,
    &piCall)

Classes with static APIs are instantiated by directly invoking their constructor.