Library resapp_lib: Class ResidentApplication

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 ResidentApplication object provides an interface between built-in applications and the ResidentFido driver. It provides API for creating and destroying the AppBase object for an application, and also API for getting attributes for the application (its name, icon, etc.).

This is an abstract class and cannot be directly instantiated.

#include <resapp/resapp.h>

• Class Data and Methods
  • Inherited Data and Methods
• Ancestors
• Descendants
• OVERVIEW
• Descriptions of Class Data and Methods

Class Data and Methods

Back to the top of ResidentApplication

Ancestors

Back to the top of ResidentApplication

Descendants

Back to the top of ResidentApplication

OVERVIEW

This object automatically registers with the ResidentFido driver, so the ApplicationManager and ApplicationCache know that this application is available, and can be loaded via ApplicationCache::Goto() and SwitchTo(). The UAL associated with this application can be generated by prepending "/rom/" to the identifier that was passed to the ResidentApplication constructor -- for example, if the identifier was "memo", then the memo application could be launched by invoking ApplicationCache::Goto("/rom/memo/").

When the system starts up and shuts down, the AppInitialize() and AppCleanup() member functions are invoked and can be overridden by the application; note that at this time the application has not been "loaded" (no AppBase object has been created and no thread has been created for the application), so the application is rather limited in what it can do in these handlers (it cannot create timers or register listeners, or perform other operations that depend on the current thread).

When an application is about to be loaded, the system will invoke CreateAppBase() on the associated ResidentApplication object, which the application can subclass to create its appbase object. It is also acceptable to declare a single static AppBase object and return a pointer to it. This option is less RAM-efficient, as ideally you don't want to have an AppBase object in RAM when the application is not loaded.

When the application is unloaded from the system, DestroyAppBase() is invoked. The default handler just frees the appbase object, but if an application is using a statically defined AppBase, it should override this to do nothing.

Note that CreateAppBase() is invoked BEFORE the application is running (before its Thread and MessageQueue have been created), so applications should not register listeners, create timers, or perform any other operations that depend on an application thread in this handler. DestroyAppBase() is invoked just before the application Thread and MessageQueues are destroyed, so applications are similarly limited in what they can do in this handler.

Applications can define various attributes (name, icon, stack size, etc.) by statically defining AppAttributeData objects. To make the creation of these attributes simpler, various subclasses have been defined (e.g., AppNameAttribute).

Back to the top of ResidentApplication

Constructor for ResidentApplication object.

Parameters:

in identifier

A string that uniquely identifies this application. This is not visible to the user.

in autoLaunch

If true, this application will automatically launch itself on system startup. Note that this should not be used for apps that can be replaced by new apps read in from the file system, as this always loads the application from ROM.

Prototype:

    ResidentApplication(const TCHAR *identifier, Boolean autoLaunch = FALSE);

Back to the top of ResidentApplication

void AppInitialize(void);

AppInitialize is invoked when the system first boots up. It can be overridden to perform initialization for an application. Note that it is invoked when the system starts, not when the application is loaded.

By default this function does nothing.

See also: AppCleanup

Prototype:

    virtual void AppInitialize(void);

Back to the top of ResidentApplication

void AppCleanup(void);

AppCleanup is invoked by the system when the system is shutting down. It can be overridden to perform cleanup duties for an application. Note that it is invoked when the system shuts down, not when the application is unloaded.

By default this function does nothing.

See also: AppInitialize

Prototype:

    virtual void AppCleanup(void);

Back to the top of ResidentApplication

AppBase *CreateAppBase(void) ;

CreateAppBase is called when an application is loaded, to create an AppBase object for the app. If the application wants to define its AppBase object statically, then the application should also provide a DestroyAppBase() handler which does nothing (the default DestroyAppBase handler invokes the delete operator on the AppBase, which is not desired for statically defined objects)

Return value: Pointer to an AppBase object for the new application, or NULL if one could not be created due to lack of heap space.

See also: DestroyAppBase();

Prototype:

    virtual AppBase *CreateAppBase(void) = 0;

Back to the top of ResidentApplication

void DestroyAppBase(AppBase *app);

DestroyAppBase is called right before an application thread exits, to destroy a dynamically allocated AppBase object. If the AppBase object is defined statically, this member function should be overridden; the default handler frees the passed-in pointer.

Parameters:

in app

The AppBase object that was previously returned by CreateAppBase.

Prototype:

    virtual void DestroyAppBase(AppBase *app);

Back to the top of ResidentApplication