This class is only available in the RT environment; it plays the same role as the CWinApp class in MFC: an application specific class must be derived from CIApp and exactly one instance of that class must be declared statically. Creating an object with a class derived from CIApp forces a main thread to be activated, which in turn calls the class calls according to the following flow of control:

int main(int argc, char * argv[])
{
    // set up theApp 
    if (theApp->InitInstance()) { 
        while (theApp->DoForever()) 
            ; 
        return theApp->ExitInstance();
    } 
    return 1;
}

Class members

Constructor

Destructor

Create

InitInstance

DoForever

ExitInstance

OnNotify

GetApp

Member variables

These member variables are only available to the members of the class and its derived classes:

int m_iArg;      // copy of argc 
char **m_pArg;   // copy of argv

Inherited functions

Attach, Detach and Lookup will call Fail when called for an application object. The operators will work, but since there can be only one application object, they do not make much sense. Other functions inherited from CIThread can be used normally.

CIApp::Constructor

The constructor must be activated exactly once for a static declaration similar to the following example (any name may be used instead of theApp and "name"):

CIMyAppp theApp("name");

The name passed as argument is used to catalog the RT process object in the root directory (this is an exception to the rule on naming in CISemaphore); the name should not be longer than 12 (ASCII or Unicode) characters and may not contain backslashes ('\'). If the name is empty, the RT process object is not cataloged at all.

CIApp::Destructor

Since the application object is declared statically and there is only one such object, the destructor is never called explicitly.

CIApp::Create (for internal use)

Although there is a Create call to get the application started, it is not intended for further use; in fact, any call after the first one will fail.

CIApp::InitInstance

See also CIThread::InitInstance. This call is called by the framework at the start of the process and should never be called explicitly. It typically creates other objects required in the process and is normally overruled with an actual implementation. It should return TRUE when all is well, FALSE when the process must be terminated.

This call catalogs the RT process object in the root directory and prepares the notification mechanism. When overruling, it is recommended to include a call to the default call, as in this example:

BOOLEAN CIMyApp::InitInstance()
{
    // actions that must precede the default init
    if (!CIApp::InitInstance())
        return FALSE;

    // actions that must follow the default init

    return TRUE; // or FALSE if initialization failed
}

CIApp::DoForever

See also CIThread::DoForever. The body of the main thread consists of a loop, where the framework calls CIApp::DoForever until it returns FALSE; it should never be called explicitly. The call may be overruled if necessary; CIApp::DoForever waits indefinitely for a message using the call RtNotifyEvent, calls OnNotify for it and returns the latter call's result.

CIApp::ExitInstance

See also CIThread::ExitInstance. CIApp::ExitInstance is called by the framework at the end of the main thread and should never be called explicitly; upon its return the process is deleted. The call typically deletes all objects created by InitInstance and it is normally overruled with an actual implementation. It should return the value to be returned by main.

CIApp::ExitInstance removes the process name from the root directory (if the name is not empty). When overruling, it is recommended to include a call to the default call, as in this example:

int CIMyApp::ExitInstance()
{
    int iResult;

    // actions that must precede the default exit 

    iResult = CIApp::ExitInstance();
    if (iResult) 
        return iResult;

    // actions that must follow the default exit 

    return 0;   // or nonzero if cleaning up failed
}

CIApp::OnNotify

CIApp::OnNotify is called by the framework when a notification has been received via the call RtNotifyEvent; it should never be called explicitly. CIApp:: OnNotify should return FALSE to terminate the process. When overruling this call, there is no need to call the default call.

Syntax

BOOLEAN CIApp::OnNotify(
    LPEVENTINFO lpEventInfo
);

Parameters

lpEventInfo

Points to the notification structure received from the call RtNotifyEvent.

CIApp::GetApp (static)

This call can be called to obtain a pointer to the application object.

Syntax

static CIApp *GetApp(void);

An alternative is to declare the application object as extern:

extern CIMyApp theApp;