Library shell_lib

All Classes, All Libraries

Index: A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z

• Classes
• Data
• Functions
• OTHER_DOCUMENTATION

Classes

AlarmManager

The AlarmManager class provides API that applications can use to register real time alarms. When the specified date and time arrives, the application is launched if it is not already running, and the event is dispatched.

AppCachePolicy

The ApplicationCache class provides API for launching and switching between applications. The AppCachePolicy class provides hooks for OEMs to use to implement device-specific policy as to when applications should be unloaded. When various system events occur (no visible applications, application being loaded, etc.) or ApplicationCache API is invoked (PreventUnloading(), etc.), the corresponding AppCachePolicy member functions are invoked to allow OEMs to customize the device behavior. OEMs can either replace the existing behavior or call the baseclass handlers that implement the default functionality, which is documented along with each member function.

ApplicationCache

The ApplicationCache class implements the public API for loading and unloading applications. The code that actually implements the application loading and unloading mechanism lies in a separate MCMApplicationCache object, which runs on the MCM thread. However, the public API will be called from other threads, so it consists of static functions that send messages to the MCM thread to call member functions on the MCMApplicationCache.

LoadedApps

The LoadedApps class provides API for determining the number of currently loaded applications and getting a pointer to each one. There is built-in synchronization (no changes to the window system can occur while a LoadedApps object exists in the system, and no applications can be loaded or unloaded), so typically it is declared as a local variable within a function and is quickly and automatically destroyed. To help ensure this, dynamic instantiation of LoadedApps objects (e.g. LoadedApps applications = new LoadedApps) is prohibited. Note that since the LoadedApps object grabs exclusive access to the window system, it is likely that other applications in the system will be unable to run while the LoadedApps object exists. It is important that code destroy the LoadedApps object as quickly as possible (perhaps by putting the LoadedApps object in a nested scope in a function). Furthermore, it is important that any code that uses the LoadedApps object destroy the object before making a call that might block the thread. Note that only the existence of the AppBase is guaranteed (the application itself may be modifying the various data members on a different thread). Callers may only safely invoke a very small set of AppBase member functions from other threads: GetMessageQueue(); GetFidoDriver(); GetUAL(); Example:

    EnumerateLoadedApps()
    {
      LoadedApps apps;
      for (i = 0 ; i < apps.GetCount() ; i++) {
          // When i=0, app = the environment shell app. If we want to
          // ignore the environment shell app, we should start with app
          // #1, not app #0.
          AppBase *app = apps.GetApp(i);
          ...perform operation on the app...
      }
      ...LoadedApps is automatically deconstructed when we exit the function...
    }

ShellAppBase

ShellAppBase is the base class for any Environment Shell application in the system.

Back to the top of shell_lib

Data

Back to the top of shell_lib

Global Functions

Back to the top of shell_lib

OTHER_DOCUMENTATION

• Overview
• Usage and Implementation
• Applicaton Architecture

Back to the top of shell_lib

enum AlarmManagerError;

This is the set of errors that AlarmManager API can return.

AME_SUCCESS

No error - operation succeeded.

AME_DB_ERROR

There was an error accessing the alarm database.

AME_INVALID_YEAR

The year passed to SetAlarm was greater than 9999.

AME_INVALID_UAL

The passed UAL was too long or was otherwise invalid.

AME_INVALID_CONTEXT

The passed context string was too long or was NULL.

AME_INVALID_HANDLE

The passed AlarmHandle does not correspond to a registered alarm (either it has an incorrect value, or the alarm associated with it has already been deleted or dispatched).

AME_INSUFFICIENT_MEMORY

There was not enough free memory to complete the requested operation.

Declared as:

enum AlarmManagerError {
    AME_SUCCESS,
    AME_DB_ERROR,
    AME_INVALID_UAL,
    AME_INVALID_YEAR,
    AME_INVALID_CONTEXT,
    AME_INVALID_HANDLE,
    AME_INSUFFICIENT_MEMORY
};

Back to the top of shell_lib

const uint32 MAX_ALARM_STRING_LENGTH = DB_MAX_SMALL_VAR_SIZE/sizeof(TCHAR);

The maximum length for the UAL or context string stored with an alarm. Note that this is a length, and includes the NULL terminator, so if you are specifying a buffer to hold a context string, you should define it like this:

TCHAR context[MAX_ALARM_STRING_LENGTH];

Declared as:

const uint32 MAX_ALARM_STRING_LENGTH = DB_MAX_SMALL_VAR_SIZE/sizeof(TCHAR);

Back to the top of shell_lib

typedef int32 AlarmHandle;

This is a unique value that identifies a registered alarm event.

Declared as:

typedef int32 AlarmHandle;

Back to the top of shell_lib

enum AppCacheError

AppCacheError is enumerated type that denotes any error codes returned when invoking various ApplicationCache API.

ACE_SUCCESS

No error.

ACE_UAL_NOT_FOUND

No application corresponding to the passed UAL was found.

ACE_INSUFFICIENT_MEMORY

There is not enough free memory to load the application.

ACE_MEDIA_ERROR

An error was encountered trying to read a dynamically loaded application.

Declared as:

enum AppCacheError {
    ACE_SUCCESS,
    ACE_UAL_NOT_FOUND,
    ACE_INSUFFICIENT_MEMORY,
    ACE_MEDIA_ERROR

Back to the top of shell_lib

const uint32 ENV_SHELL_INDEX = 0;

Passed to LoadedApps::GetApp() to get the AppBase object corresponding to the Environment Shell application.

Declared as:

const uint32 ENV_SHELL_INDEX = 0;

Back to the top of shell_lib

const uint32 ACTIVE_APP_INDEX = 1;

Passed to LoadedApps::GetApp() to get the AppBase object corresponding to the active application, assuming that an EnvShell application is running.

Declared as:

const uint32 ACTIVE_APP_INDEX = 1;

Back to the top of shell_lib