Library shell_lib: Class AppCachePolicy

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

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.

#include <shell/policy.h>

• Class Data and Methods
  • Inherited Data and Methods
• Ancestors
• Descendants
• CREATING A POLICY OBJECT
• EXITING APPLICATIONS
• Descriptions of Class Data and Methods

Class Data and Methods

Back to the top of AppCachePolicy

Ancestors

Back to the top of AppCachePolicy

Descendants

Back to the top of AppCachePolicy

CREATING A POLICY OBJECT

The ApplicationCache only interacts with a single AppCachePolicy object. The Shell library provides a default, but the Environment Shell application can provide its own instance of AppCachePolicy if it wants to customize device behavior. The AppCachePolicy object registers itself as the active object in its constructor, so if an Environment Shell (or other module) provides multiple instances, the one that was most recently constructed will be the active one. When the active policy object is destroyed, the system reverts to the default provided by the Shell library, not the previously registered one.

In general, all of the AppCachePolicy API is invoked on the Environment Shell thread, with a few exceptions:

* The initial AppLoading() and BringToForeground() calls are performed on the system startup thread, because the Environment Shell application hasn't been loaded yet.

* AppExiting is invoked on the thread of the application that is exiting. There are too many weird race conditions when unloading and reloading applications to post AppExiting calls to the Environment Shell thread (it would be possible to get an AppExiting call for an application that had been reloaded in the meantime).

Back to the top of AppCachePolicy

EXITING APPLICATIONS

When the AppCachePolicy decides that it is time to unload an application, it invokes AppCachePolicy::UnloadApplication from the EnvShell thread. This queues up a message on the application thread to invoke AppBase::Exit() on the application's AppBase. Keep in mind that the individual application's AppBase may choose to override and ignore the Exit() invocation.

Back to the top of AppCachePolicy

Constructor that automatically registers this policy object with the system.

Prototype:

    AppCachePolicy();

Back to the top of AppCachePolicy

~AppCachePolicy();

Destructor that unregisters this object with the system.

Prototype:

    virtual ~AppCachePolicy();

Back to the top of AppCachePolicy

Result UnloadApplication(AppBase *app);

Invoked by OEM AppCachePolicy objects to force an application to be unloaded. It should only be called from the Environment Shell thread.

This call will queue up a request to the application to exit. However, this is no guarantee that the application will actually be unloaded. It is possible for a new ApplicationCache::SwitchTo() or Goto() invocation for the application to come in before the application has exited, which will cancel the exit. Additionally, applications may intercept AppBase::Exit() and simply fail to pass this call off to the base class, thereby preventing themselves from exiting.

Parameters:

in app

The AppBase object associated with the application the caller wants to unload.

See also: AppBase::Exit(), ApplicationCache::SwitchTo()

Prototype:

    static Result UnloadApplication(AppBase *app);

Back to the top of AppCachePolicy

void ActiveApplicationClosed(void);

Invoked when an application is the active application and has exited (this typically only happens if the application forces itself to exit). AppCachePolicy objects can override this to switch to some type of default application.

Prototype:

    virtual void ActiveApplicationClosed(void);

Back to the top of AppCachePolicy

void AllowUnloading(const TCHAR *ual);

Called to once again allow an application to be unloaded. If AllowUnloading() is called more times than PreventUnloading(), the extra calls will be ignored.

As is the case with PreventUnloading(), this API is only defined to provide input to the AppCachePolicy; the AppCachePolicy is still free to unload applications whenever it wants.

See also: PreventUnloading()

Prototype:

    virtual void AllowUnloading(const TCHAR *ual);

Back to the top of AppCachePolicy

void AppExiting(AppBase *app);

Invoked when an application is being unloaded. OEMs typically override this to know when a given application actually exits, so that they can update any internal LRU tables they have, etc.

Note that this is invoked on the exiting application's thread, not on the Environment Shell thread, as is the case with the rest of the API.

The default handler invokes FidoDriver::UnloadApplication() on the appropriate FidoDriver.

Parameters:

in app

The AppBase associated with the object that is exiting.

Prototype:

    virtual void AppExiting(AppBase *app);

Back to the top of AppCachePolicy

AppCacheError AppLoading(const TCHAR *ual);

Invoked to load an application from a FidoDriver and create a thread for it. OEMs typically override this function to unload previously loaded applications, to make room for the new application.

The default handler invokes FidoDriver::LoadApplication on each of the currently loaded Fido drivers until the application is loaded, creates a thread, and returns a pointer to the AppBase object to the caller. The caller is then free to invoke BringToForeground(), set the context for the application, or do whatever else is required.

Parameters:

in ual

The UAL of the application being loaded.

See also: ApplicationCache::SwitchTo()

Prototype:

    virtual AppCacheError AppLoading(const TCHAR *ual);

Back to the top of AppCachePolicy

AppCacheError BringToForeground(AppBase *app);

Invoked when ApplicationCache::SwitchTo() is called, passing the UAL of an already-loaded application. OEMs that are implementing some kind of LRU cache can override this to update their cache information.

The default handler sets the AppBase visible, moves it to the front of the linkage, and invokes AppBase::Raise() on it. It then sets the old active application not visible and invokes AppBase::Lower() on it.

Parameters:

in app

The AppBase object to bring to the foreground.

See also: ApplicationCache::SwitchTo()

Prototype:

    virtual AppCacheError BringToForeground(AppBase *app);

Back to the top of AppCachePolicy

void PreventUnloading(const TCHAR *ual);

Invoked when the application has asked the ApplicationCache not to unload an application. Typically this is done before a lengthy operation is started. A counter is kept, which means that if PreventUnloading is called twice, then AllowUnloading() must also be called twice before the system will think that the application is ready to be unloaded.

Note: The policy for when applications are loaded and unloaded is implemented entirely within the AppCachePolicy. PreventUnloading() will let the AppCachePolicy know what the application's wishes are, but the AppCachePolicy is still free to unload the application.

The default behavior is to do nothing; this API is provided to allow applications to provide input to the AppCachePolicy, but policy objects are free to ignore these calls.

See also: AllowUnloading()

Prototype:

    virtual void PreventUnloading(const TCHAR *ual);

Back to the top of AppCachePolicy