Hello App: hello.mreg

Contents

hello.mreg

/**

* hello.mreg - MAE message registration for "hello" channel (C++ version)

* Written by Anthony V. Edwards

* 820 Churchill Drive, Chapel Hill, NC 27517

* ave@hanoversoft.net

* A MAE app is expected to handle messages/events from multiple users or multiple instances.

* This file directs MAE as to how you want those messages/events handled.

* Each message/event has an id that is used to pull up the appropriate instance of HelloApp.

* An instance of HelloApp is handy for maintaining session data.

* If you don't want to maintain session data, explicitly set appclass to nothing.

* This file contains directives for the genmae tool to generate msgHello.cpp, which contains code to

* 1) initial setup by integrating with MAE daemons (e.g. usergw and guibroker for the UI)

* 2) respond to messages/events from MAE, such as user menu selection

* 3) handle API calls (the simple Hello app does not define any API calls) from other MAE apps - asynchronous events

* 4) handle RPC calls (the simple Hello app does not define any API calls) from other MAE apps - synchronous events

* 5) respond to user input controls such as pull-down selection, text responses, etc.

* 6) process other files (such as .cpp or .ui files) that may contain more directives (in comments)

* Comments in this file are included in generated file output, so commenting well here means commenting well elsewhere.

* To generate msgHello.cpp, use

* genmae hello.mreg -msg msgHello.cpp

* To generate C method prototypes for callbacks from this file, which is

* useful for creating/modifying HelloApp.h, use

* genmae hello.mreg -hcpp

* To generate C method dummy code for callbacks from this file, which is

* useful for creating/modifying HelloApp.cpp, use

* genmae hello.mreg -cbcpp

* If we define #api/#msg blocks for an API for other MAE apps to use, we

* generate the include file and C++ source code using

* genmae hello.mreg -apicpp -apih

* To generate wiki documentation on message handling performed here, we use

* genmae hello.mreg -wiki

* which is used in our Hello app documentation stored in /usr/mae/html/doc/hello.wiki

* To convert a .ui file into fully proper .html (removing genmae clues), use

* genformcode genformcode html helloPrompt.ui ../../html/record/helloPrompt.html

// Our app's include file, so we have ready access to our context

// Generated code for msgHello.cpp, HelloApp.cpp, and HelloApp.h will include this

// (Use #apiinclude for API files.)

#include "hello.h"

// We communicate within MAE using our own unique channel name 'hello

#channel=hello

// Internally, we use the HelloApp class to manage session instances

#appclass=HelloApp

// We maintain a cache of multiple sessions in the HelloCache vector

#appcache=HelloCache

// This is the code to locate our instance of HelloApp in the cache

// Or exit out if there's an error.

#idcode

// Track user-specific state (if needed)

DbRecNum user_id= device.getUserId();

int pos= HelloCache.findPos(user_id);

if (pos < 0 && user_id > 0) {

// a new connection - add to cache

HelloApp newUser(user_id);

// remember our path to the user

newUser.setDevice(device);

// add this user to our in-memory cache

pos= HelloCache.add(user_id, newUser);

}

if (pos < 0) {

// We don't have a match for this device

string msg= (string)"Unknown device (Uid=" + user_id + ",Conn="+device.getConnectionId()+",App="+device.getAppMode()+",tag="+device.getRegion()+") for " + request;

MAE::log (msg);

MAE::mgmt.incrementInputErrorCount();

return;

}

// any connection-specific data

HelloApp & instance= HelloCache[pos];

// Here's a code block for any code that should be executed before the message is processed

#msgprecode

// Here's a code block for any code that should be executed after the message is processed

#msgpostcode

/** Initiate a new user session.

* @param param - inbound variables from UserDevice::run() (if any)

#userstart void userstart(XMLData & param)

//////////////// Declare the app menus

// We tell guibroker what our menus are. Before the user reaches us, guibroker

// renders hello.html and populates the page with these menu options.

// As the user clicks on a menu option, we receive the message (#msg) associated

// with that menu option. When we receive that message, MAE calls the method we

// are here associating with the menu. It's menu registration & callback.

// Here's the menu option Display->From DB, which queries the DB to determine the user's name, then says hello

#menu "Display" "From DB"

#msg "fromdb" menu_Display_FromDB();

// Here's the menu option Display->Clear, which sends us the message clrdisp, which in turn calls menu_Display_Clear()

#menu "Display" "Clear"

#msg "clrdisp" menu_Display_Clear();

// Here's the menu option Display->Help, which sends us the message help, which in turn calls menu_Display_Help()

#menu "Display" "Help"

#msg "help" menu_Display_Help();

// Here's how the user quits: menu option Display->Quit

#menu "Display" "Quit"

#msg "quit" menu_Display_Quit();

// Read and process these .ui files to extract out more directives.

// Note that you won't see directives in the .ui file; the genformcode program

// is needed generate them for genmae (which happens implicitly).

// Although only a .ui file is specified here, you can also specify a .cpp file

// which is handy when your .cpp code is generating buttons or text input areas

// and you want to configure callbacks right there (in the comments).

#process "helloPrompt.ui"