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

Developer

resources

Notifications

IShell's notification mechanism allows a Brew MP class to notify other classes that certain events have occurred. To receive a notification, a class must register its interest with the AEE Shell, specifying the ClassID of the notifier class and the events for which notification is desired. When an event requiring a notification occurs, the notifier class calls ISHELL_Notify( ), sending a notification to each class that has registered to be notified of the occurrence of that event.

The AEE Shell provides two ways for a class to register for notification of an event:

  • You can register by specifying information about the notification in your application's CIF/MIF file through the Notifier primitive (see the Resource File and Markup Reference). This method of registering is used by applications that must be notified of events even when they are not running. Brew MP maintains a list of notifications based on the information in the MIF. Brew MP can send a notification to an applet that isn't running, wake up the applet, and the notification is received by the application's HandleEvent function. One example is a call-logging application that receives notification of each incoming and outgoing call; such an application would need to process notifications even while the user was not running the application to display the call log.
  • If notification is required only at certain times while your application is running, you can call ISHELL_RegisterNotify( ) to initiate event notification. For example, a game application might display a message when an incoming text message arrives that would allow the user to open and read the message or continue playing the game. This application requires notification of incoming text messages only while the user is actually playing the game, so it would call ISHELL_RegisterNotify( ) when the user starts to play the game.

The following diagram shows how applications register for notifications.

Receiving Notifications

To receive a notification, the application must register for notifications. This can be done in one of two ways:

  • ISHELL_RegisterNotify() can be called during run-time to register for a notification from a given applet (ClassID). Notifications can only be received after this call is made and registered with the BREW Shell.
  • The notifications to receive can be listed in the application MIF. This enables receipt of notifications even when the application isn't running. This approach can be used to notify when the BREW Shell is first initialized by listening to a notification from AEECLSID_SHELL called NMASK_SHELL_INIT.

For example, to register for FLIP, KEYGUARD, and SCR_ROTATE notifications in the CIF, add the following Notifier primitives to the CIF:

Notifier {
   clstype = AEECLSID_DEVICENOTIFIER,
   clsnotify = AEECLSID_MyApp,
   mask = NMASK_DEVICENOTIFIER_FLIP,
}
Notifier {
   clstype = AEECLSID_DEVICENOTIFIER,
   clsnotify = AEECLSID_MyApp,
   mask = NMASK_DEVICENOTIFIER_KEYGUARD,
}

Notifier {
   clstype = AEECLSID_DEVICENOTIFIER,
   clsnotify = AEECLSID_MyApp,
   mask = NMASK_DEVICENOTIFIER_SCR_ROTATE,
}

To register for FLIP, KEYGUARD, and SCR_ROTATE notifications using ISHELL_RegisterNotify(), add the following code to the application:

IShell_RegisterNotify(piShell, AEECLSID_MyApp, AEECLSID_DEVICENOTIFIER,
         NMASK_DEVICENOTIFIER_FLIP | NMASK_DEVICENOTIFIER_KEYGUARD |
         NMASK_DEVICENOTIFIER_SCR_ROTATE);

When an application registers for notifications, it receives the EVT_NOTIFY event when one of the specified events occurs. The application can use the notification masks to determine which event occurred. For example:

static boolean c_app_HandleEvent(c_app* pMe, AEEEvent eCode,
            uint16 wParam, uint32 dwParam)
{  
   
   switch (eCode){
      case EVT_NOTIFY:
      {
         if(dwParam){
            AEENotify *pNotify = (AEENotify *) dwParam;
            AEEDeviceNotify * pDevNotify = NULL;

            //first check if it is a device notification
            if ( (AEECLSID_DEVICENOTIFIER == pNotify->cls){
               // check if it is SCR_ROTATE
               if(NMASK_DEVICENOTIFIER_SCR_ROTATE | pNotify->dwMask){
                  // pDevNotify->wParam will the the same wParam that
                  // is sent with EVT_SCR_ROTATE
                  // pDevNotify->dwParam will the same dwParam that
                  //is sent with EVT_SCR_ROTATE

                  pDevNotify = (AEEDeviceNotify *) pNotify->pData;      
               }
               // check if it is FLIP
               if(NMASK_DEVICENOTIFIER_FLIP | pNotify->dwMask){
                  // pDevNotify->wParam will the the same wParam that
                  // is sent with EVT_FLIP
                  // pDevNotify->dwParam will the same dwParam that is
                  // sent with EVT_FLIP

                  pDevNotify = (AEEDeviceNotify *) pNotify->pData;

               }
            // continue to check HEADSET, KEYGUARD if needed…                 
            }
            
         }
         break;
      }
   }
}

Sending Notifications

To send a notification, call ISHELL_Notify(). This results in all the applets registered for this notification receiving an event called EVT_NOTIFY, along with the data sent with ISHELL_Notify().

The http://developer.brewmp.com/reference/api-all contains more information on the functions mentioned, as well as related functions for communicating between applets such as ISHELL_BrowseURL(), ISHELL_PostURL(), and ISHELL_SendEvent().

For more information on notifications, see the Application Management Technology Guide for developers in http://developer.brewmp.com/resources on the Brew MP website.