Python MgmtClient

Index Home MAE Python Interface > Python Index > Python MgmtClient

Module MgmtClient

Public Properties

Public Methods

setfield(device, table, field, value)

Update/Replace the table and field entry with the value provided

Return value: true if sent successfully

settext(device, text, style)

Replace the display region with the text provided.

Return value: true if sent successfully

write(device, text, style)

Append to the display reagion with the provided text for the user specified

Return value: true if sent successfully

writeln(device, text, style)

Append to the display reagion with the provided text for the user specified, followed by a line break.

Return value: true if sent successfully

writewiki(device, text)

Convert the text from wiki text (see wiki2doc) and display to the display region.

Return value: true if sent successfully

addhotspot(device, text, action, cbdata, style)

Append the tagged area with the provided text for the user specified and make it a hot spot that triggers an action.

Return value: true if sent successfully

addhinttext(device, text)

Provide hint text to the end-user for the display region. Exact implementation up to the end interface, but it may be to display text when the user hovers over the display region.

Return value: true if sent successfully

button(device, text, action, cbdata)

Append the tagged area with the provided text on a button for the user on the device specified. When clicked, it triggers a a message with the action and callback data.

format(device, control, on)

DEPRECATED - use style() instead.  Update the current display style state.

Return value: true if sent successfully

newregion(device, newtag, styleName, size)

Create a new display region inside device's current display region.

Return value: true if sent successfully

style(device, styleName)

Set the named display style for device's current display region.  See the configured properties of the style in the appropriate end-user display type (e.g. usergw uses HTML CSS).

Return value: true if sent successfully

attention(device, text)

Display a message to get the user's attention.

Return value: true if sent successfully

selection(device, value)

When a display region contains a selector, set the active selection to the value provided. If the value is not a valid selection, behavior is undefined.

Return value: true if sent successfully

chat(device, from, text)

Send a chat message to the end-user's device.

Return value: true if sent successfully

clear(device)

Clear all displayed objects and text from the current display region of the device.

Return value: true if sent successfully

show(device)

Display the objects and text inside the current display region of the device.

Return value: true if sent successfully

hide(device)

Hide the objects and text inside the current display region of the device. Make them non-visible.

Return value: true if sent successfully

newtable(device, tableName, tableType, rows, columns)

Create a table display region on the user'd device. It will be setup with the rows and columns specified.  Note that referencing one column more to the right will create that column; and referencing one more row below will create that row.

Return value: true if sent successfully

newlist(device, name, items)

Create a bulleted list that can contains items. Note that adding a list item immediately beyond the end will expand the list.

Return value: true if sent successfully

record(device, recordName, idmap, values, overwrite)

Output a record of information using a templte to map old UI ids to new ones.  For idmap, the key is the old id and the value is the new id

Return value: true if sent successfully

report(device, reportName, table, table_id)

FUTURE USE.  Output a report of information

Return value: true if sent successfully

prompt(device, query, value, promptType, xid, style)

Present the user with a question and response (text entry) box. The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

select(device, option0, options, xid, selected)

Present the user with a selection of choices.  The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

checkbox(device, query, value, xid, style)

Present the user with a selection of choices as checkboxes.  The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

textarea(device, text, xid, style, saveLabel)

Present the user with an area to type a lot of text.  The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

form(device, formName, vars, xid)

Present the user with input form template.  The xid parameter ties back to the appropriate response action and callback data to use when replying (see GuiAPI).

Return value: true if sent successfully

screen(device, name, rows, columns)

Create a terminal screen of the specified size on the user's device.

Return value: true if sent successfully

scrattr(device, attributes)

Set the current terminal screen attributes for the next character(s) to be written.

Return value: true if sent successfully

scrchar(device, row, column, letter, amount)

Write a character to the terminal screen previously defined at device's display region.

Return value: true if sent successfully

setmenu(device, menu, option, command)

Configure the end-user's device with the menu option under the specified menu.  When the end-user selects it, the specified command will be sent as a message request of the app.

Return value: true if sent successfully

unsetmenu(device, menu, option)

Remove the menu option under the specified menu on the end-user's device.

Return value: true if sent successfully

setwindow(device, windowName)

Configure the end-user's device with a window, titled with the name provided.

Return value: true if sent successfully

unsetwindow(device, windowName)

Remove/Close the named window from the end-user's device.

Return value: true if sent successfully

setindex(device, indexName)

Configure the end-user's device with the index (tab).  

Return value: true if sent successfully

unsetindex(device, indexName)

Remove the named index from the end-user's device.

Return value: true if sent successfully

newsection(device, title, sectionType, newtag)

Add a section the the UI.  Sections can be manipulated, for example expanded/collapsed.

Return value: true if sent successfully

collapseSection(device)

Collapse the section identified as the current display region.

Return value: true if sent successfully

expandSection(device)

Expand the section identified as the current display region.

Return value: true if sent successfully

displayImage(device, imageName, image_type, action, cbdata, append)

Display the referenced buffered image that has already been transferred to display channel. If an action is provided, the image can be clicked on to trigger the action with its callback data.

Return value: true if sent successfully

displayImage(device, image_id, action, cbdata, append)

Display the referenced buffered image that has already been transferred to display channel. If an action is provided, the image can be clicked on to trigger the action with its callback data.

Return value: true if sent successfully

playAudio(device, audioName)

Play the referenced audio sound.  

Return value: true if sent successfully

download(device, query, fileclass, xid)

Request that the user send the app a file.

Return value: true if sent successfully

upload(device, imageName, image_type)

Send a file to the end-user's device that has already been transferred to display channel.  

Return value: true if sent successfully

imagelibpre(device, id)

Pre-fetch and image from ImageLib.  

Return value: true if sent successfully

bufimage(device, imageName, image_type, width, height, size, binary, chunk, totalChunks, chunksize, data)

Send a chunk of data to the display chennel (to fit within a message max size).

Return value: true if sent successfully

setvar(device, variable, value)

Alter a end-user device built-in variable value.

Return value: true if sent successfully

getvar(device, variable, value)

Alter a end-user device built-in variable value.

Return value: true if sent successfully

run(device, appname, startParams)

Switch the user from running one app to a different app using the provided parameters.

Return value: true if sent successfully

stop(device)

Stop running the current application.

Return value: true if sent successfully

userAccountChange(userId, action, value)

Take an action on a user's account.

Return value: true if sent successfully

registerApp(appmode, apptype, action, contentInputType, contentOutputType, operations, msgchannel, privatePages)

Register an app mode with UserGW. This captures all URL activity for URLs that begin with that appmode.

Return value: true if sent successfully

startraw(device, statusCode, contentType)

Declare to UserGW that response output is ready to send.

Return value: true if sent successfully

writeraw(device, text, isBinary)

Output text to the connection without modifying the text at all.  If the text is binary, it is converted from hex codes to binary before transmission.

Return value: true if sent successfully

closeraw(device)

Append to the display reagion with the provided text for the user specified

Return value: true if sent successfully

send(request, params)

simpleEncrypt(text, offset)

Return str value:

simpleEncryptLike(text, likeOtherText)

Return str value:

isSimpleEncrypted(text)

Return bool value:

simpleDecrypt(text)

Return str value:

prompt(device, question, prefillAnswer, queryType, cbapp, cbtag, cbdata, style)

select(device, question, choices, cbtag, cbdata, defaultValue)

textarea(device, question, origText, cbtag, cbdata, style, saveButtonLabel)

checkbox(device, question, cbtag, cbdata, defaultValue, style)

form(device, formName, formDefaults, cbtag, cbdata)

run(device, appname, appparams)

download(device, query, cbtag, cbdata, fileclass)

registerMenu(device, menuname, menuoption, action)

registerKey(device, keystroke, action)

registerHotspot(device, region, action)

redirectHotspot(device, region, otherapp)

error check

registerMouse(device, region, action)

registerCommand(device, cmd, cmdparams)

send(request, params)

htmlize(url)

Converts a string to a string usable inside HTML code.

The returned pointer should be free()ed by the calling routine.

Return str value:

urlize(url)

Operations performed:

change % to %25

change = to nothing

change + to %3b

change space to %20

change # to %23

Return str value:

sendImage(device, iid, errmsg, action, cbdata)

saveToImageLib(device, filename, filetype, filecontent, xid, category)

saveToImageLib(image_id, filename, filetype, filecontent, category)

updateImageLib(image_id)

saveToImageLib(image_id, filecontent)

setImageCategory(image_id, category)

setImageName(image_id, name)

setImageType(image_id, type)

newImage(table, id)

send(request, params)

response(device, xid, text)

chat(device, text)

cmd(device, cmd)

key(device, key)

click(device)

mouse(device, direction, x, y, action, cbdata)

hotspot(device, action, cbdata)

upload(device, fileclass, filetype, imagelibid, xid)

refresh(device)

select(device, value)

online(device, appparams)

withdraw(device)

timeout(device)

send(request, params)

open(name, mode, cbtag, cbdata)

putchar(ioId, c, ioChannel)

write(ioId, text, ioChannel)

write(ioId, data, ioChannel)

seek(ioId, offset, ioChannel)

lock(ioId, exclusive, wait, ioChannel)

unlock(ioId, exclusive, wait, ioChannel)

close(ioId, ioChannel)

fsverify(node, ioChannel)

fsreview(dirResourceId, ioChannel)

fsconfirm(node, size)

fsupdate(node, change, size)

ls(maepath)

stat(maepathandfilename, statbuf)

send(request, params, channel)

send(request, params)

key(device, key, keycode)

redraw(device)

send(request, params)

Class Cache

Public Methods

__init__(self, objType, size)

Constructor.

__del__(self)

Destructor

add(self, newKey, newOne)

Add a record to the cache. It must be valid().

Return int value:

removeKey(self, key)

Remove a record from the cache

Return bool value:

remove(self, pos)

Remove a record from the cache

Return bool value:

findPos(self, searchKey, fetchIfMissing)

Locate the cache position (-1 if not found)

Note: Pull into cache if fetchIfNotFound is True

Note: key must be a positive (non-zero) number

Return int value:

exists(self, searchKey)

Check if key exists in list

Return bool value:

get(self, key)

Get pointer to data for the key. Check if result is valid().

Note: key must be a positive (non-zero) number

__getitem__(self, pos)

This method allows the class instance to be indexed, e.g. HelloCache[2] to get the second element (not key==2)

Return value: the instance at position

__len__(self)

Return the size of the cache when using the len() function

Class Datastore

Summary

This class abstracts database protocols and allows an app to use this interface to perform database table queries and changes.

This class connects to dbbroker, which actually performs the database manipulation.  Note that dbbroker can be configured to connect to a variety of databases; this gets rid of app responsibility for database connection and syntax; an app can simply use the database.

It is safe (and convenient) to create an instance of this class for each table your program uses.

If you have an existing database table and you want to create a class interface to it, consider using genmae like this:

genmae db2h tablename > classname.h

genmae py classname.h > classname.py

Likewise, if you create .h file with the core class variables, you can use genmae to create the SQL code to setup the table, like this:

genmae h2sql classname.h > tablename.sql

Note that database manipulation commands will block program execution until a response from dbbroker is received.

Public Properties

Public Methods

__init__(self, tableName)

Constructor to initialize our data structure.  This does not yet setup the connection to dbbroker.

valid(self)

Determine status of our connection to database - is it valid?

Return int value: True if connected to db

status(self)

Get the status of the last request

Return int value: the status of the last request (see codes at top of Datastore.py)

statusOK(self)

Determine if the status of the last operator was successful.

Return bool value: True if last operation successful, False otherwise.

isOpen(self)

Determine if the database connection is established and ready.

Return bool value: True if db connection ready

statusMsg(self)

Return human readable status of last request.

Return str value: msg corresponding to last DB request

fieldNameToType(self, name)

fieldTypeToName(self, fieldtype)

Return str value:

errorMsg(self, rcToGetMsgFor)

Get the status message of the specified return code.

Return str value: the text of the error message

open(self, tableName)

Set the currently active table by opening it.

Return int value: the status code of the operation.

select(self, tableName)

Identifical to open().  Set the currently active table by opening it.

Return int value: the status code of the operation.

connected(self)

Check to make sure the database connection is working.

Return bool value: True if db responding to our requests

pack(self)

Pack the database (remove deleted records), if the database supports this.

Otherwise, it is ignored.

Return bool value: True upon success, False upon failure (see statusMsg())

close(self, specifiedTable)

Signal to close this database table.

@param table name of the table to close; if none, then last table used

Return bool value: True upon success, False upon failure (see statusMsg())

getTableList(self)

Get the list of defined tables.

Return value: the list of tables in the database

addField(self, fieldName, type, size, table, isIndex)

Obsolete. Add a field to the named database table.

Return 0 value: field id of new field

getFieldId(self, fieldName, table)

Query field id from field name for the named table.

Return int value: nonzero on success, 0 on failure

addFieldEnum(self, fieldName, enumName, enumId, table)

Obsolete.  Add field enumeration to the nanmed table.

Return int value: new enum value

getFieldType(self, fieldName, table)

Query a field type (string, float, etc) for the provided field name in the provided table.

Return value: the field type

addRecord(self, data, recno, table)

Add/Append a new record to the table provided, populated with the data provided.

Return value: new record number added

deleteRecord(self, recno, table)

Delete a record in the named table.

Return bool value: transaction status (see statusMsg())

lockRecord(self, recno, table)

Lock a record in the named table; prevent other applications from modifying this record until it is unlocked.

Return bool value: transaction status (see statusMsg())

unlockRecord(self, recno, table)

Unlock a record in the named table, allowing other applications to now modify it.

Return bool value: transaction status (see statusMsg())

clearField(self, recno, fieldName, table)

clear/empty the value for the field with this field name

Return bool value: transaction status (see statusMsg())

setValue(self, recno, fieldName, value, table)

change a string value identified by field ID

@param field name of the field in which to set the value

Return bool value: transaction status (see statusMsg())

setRecord(self, recno, newValues, table)

change several field values at once

@param newValue key/value pairs for new field/value changes

Return bool value: transaction status (see statusMsg())

getFieldInt(self, recno, fieldName, table)

get an int field value identified by field name

Return int value: the int value or -1 if unsuccessful

getFieldString(self, recno, fieldName, table)

get a string field value identified by field name

Return str value: the string value or zero length string if unsuccessful

getFieldFloat(self, recno, fieldName, table)

get a float field value identified by field name

Return float value: the float value or ??? if unsuccessful

getFieldEnumValue(self, recno, fieldName, table)

get an enum value identified by field name

Return str value: the enum value or zero length string if unsuccessful

getRecord(self, recno, fields, table)

get an int field value identified by field name

@param fieldName name of the field to get

Return value: key/value pairs of field/value values from record.  Error if empty, check status()/statusMsg().

getFieldEnumValueAsInt(self, recno, fieldName, table)

get an enum value as an int identified by field name

Return int value: the enum value or zero length string if unsuccessful

queryRecordsEnum(self, fieldName, value, sortby, table)

simple query for enum value by field name

Return list value: list of record numbers matching criteria

queryRecords(self, fieldName, value, sortby, table)

simple query for string value by field name

Return list value: list of record numbers matching criteria

queryRecords2(self, criteria, ANDed, sortby, table)

compound query for a field value

@param list list of field key/value pairs to be searched for

Return list value: list of record numbers matching criteria

queryExpr(self, expression, fields, sortby, table)

Using an expression, query records and return the requested fields, sorted if specified.

@param results - (output) a list of records and their fields that matched

Return bool value: True upon success

queryAllRecords(self, sortby, table)

query for all records in the named (or current) table

Return list value: recList with results which will be empty if unsuccessful

queryFieldNames(self, table)

query for all field names and types

Return value: XMLData which will be empty if unsuccessful. Otherwise key is field name, value is field type.

queryFieldIds(self, table)

query for all field names and types

connect(self)

Connect to database server.

In actuality, this only checks to make sure we're connected to the MAE daemon, commhub.

Return bool value: True on success; False on failure

doCommand(self, cmd, params)

Send a command for dbbroker that has no parameters. And wait for the reply.

Return bool value: True on success; False on failure

send(self, params)

Send data to commhub for DB operation

Return bool value: True if sent; False if failed

receive(self)

Wait for a dbbroker response from commhub.

Return bool value: True if reply received; False if not

encodeNewline(self, text)

commhub wants a comment to have new \n characters, so encode them

unencodeNewline(self, text)

commhub didn't let dbbroker send any \n characters, so unencode them

Class HashArray

Super class: dict

Summary

This class behaves a lot like the dict class, but with more control over the value types.

Note that all keys are strings.

Using HashArray

The HashArray data type is a key-value container.

It is typeless, but a specific type can be asserted (e.g. setBool()) or retrieved (e.g. getBool(), getInt(), etc).  It is up the the application to store/retrieve by type consistently.

This data type is very convenient for messaging.  Calling the toString() method converts the HashArray into a string.  Using the fromString() method or constructor converts it back.

Caveats

1. Numerical keys are not handled rigorously; unless numerical keys are set sequentially, you may get inconsistencies.
2. When used inside XMLData, keys must be identifers with alphanumeric characters; if non-alphanumerics are given, they will be converted to underscores when converted using toString().  XMLData requires keys to be valid XML tag identifiers.

Public Methods

__init__(self, value, separator)

Constructor

setProps(self, other)

Set the properties of the other HashArray into this HashArray, replacing any previous values

size(self)

Return the number of key-value pairs.

Return int value: # keys in hash array

empty(self)

Determine if there are no key-value pairs in the hash array.

Return bool value: True if there are no key-value pairs, False if there's at least one

set(self, key, value)

Assign a value into the dict

setBool(self, key, value)

Assign a boolean value to a key.

unset(self, key)

Remove a key/value pair from the dict

get(self, key)

Get a string value from the dict key

Return str value:

getInt(self, key)

Get a integer value from the dict key

Return int value:

getFloat(self, key)

Get a floating point value from the dict key

Return float value:

getDouble(self, key)

Get a double precision floating point value from the dict key. Same as getFloat().

Return float value:

getBool(self, key)

Get a boolean value from the dict key

Return bool value:

toString(self, separator)

Serialize the HashArray into a string.

isHashArray(text)

Examine the text string provided and determine if it's a HashArray or not.

Return bool value: True if text string is a serialized HashArray, False otherwise

fromString(self, text, separatorCharacter)

Take a text string that was generated by toString() and restore the data inside HashArray.

Return bool value: True if text could be fully decoded.

Class ImageLib

Using ImageLib

This class holds a reference to and then ultimately delivers the binary content of an image in the Image Library (the ImageLib table).  This class holds the image id, name, category, image type, height and width of the image.

Public Methods

__init__(self, id)

__init__(self, name, category)

clear(self)

__init__(self, data)

set(self, data)

append(self)

save(self)

toHashArray(self, forDB)

load(self, id)

Return bool value:

toString(self)

Return str value:

fromString(self, data)

Return bool value:

calcChecksum(self)

Return int value:

getName(self, id)

Return str value:

getHeightWidth(self, id, height, width)

Return bool value:

getType(self, id)

Return str value:

find(self, name, category)

Class Image

Summary

This class represents images within the MAE system.

Images may be drawn by the app or pulled from ImageLib database table.

Drawn images draw into a coordinate system with the size (height, width) and origin specified by the application.  For example, to create an image with a coordinate system that is 5 units wide and 4 units tall with the origin(0,0) in the center, you specify setSize(5, 4) and setOrigin(-2.5,-2).  How large the image is when it is displayed depends upon the unit size. If you'd like your 5 unit wide image to be 50 pixes wide, then specify setSize(5, 4, 10).

To display an image to the user, see the UserDevice class.

Use this class to communicate with imager, which renders them appropriately for the user.

Using Image

This data structure abstracts a vector image.  The API is used to describe the image.  It is not rendered into JPG, PNG, SVG, or other specific image technology until it is ready to be rendered to the end-user.  Rendering is performed by the imager daemon.

The API could be richer, but the API must be able to render to each of the ultimate image types.

The Image class may refer to an existing image file in a specific format via ImageLib class, which specifies where to retrieve the image and the image's size.

Graphics Commnds

setSize()

setSize(double newWidth, double newHeight, int newUnitSize)

Set the canvas dimensions and specify how many pixes per unit.  For example, a 4.0x5.0 image where unit size is 10 would create a 40x50 pixel image.

setOrigin()

setOrigin(double newOriginX, double newOriginY)

Specify how many units over the origin should be located if (0,0) is the lower left

setWindow()

setWindow(double minX, double minY, double maxX, double maxY, int newUnitSize)

Specify the width and origin implicitly by specifying the window into the view.  Use this instead of setSize() setOrigin()

drawBox()

drawBox([[#Point]] corner1, Point corner2, string color, bool fill, string link)

Draw a rectangle with the corners specified.  Default color is black.  The box may be an outline or solid/fiilled.

An optional link (e.g. URL) may be provided if resulting image supports linking.

drawLine()

drawLine([[#Point]] p1, Point p2, string color, string link)

Draw a line from p1 to p2 of the color specified.

An optional link (e.g. URL) may be provided if resulting image supports linking.

drawCircle()

drawCircle([[#Point]] center, double radius, string color, bool fill, string link)

Draw a full circle with the specified center and radius.  The default color is black.  The circle may be an outline or solid/fiilled.

An optional link (e.g. URL) may be provided if resulting image supports linking.

drawText()

drawText([[#Point]] start, string text, string color, string link)

Draw text into the image with the lower left corner of the text at the start point.

drawArc()

bool drawArc([[#Point]] center, double startang, double endang, double radius, string color, bool fill)

drawPolygon()

drawPolygon([[#Point]]List p, string color, bool fill, string link)

Given a series of points, draw the enclosed polygon.  The default color is black.  The polygon may be an outline or solid/fiilled.

An optional link (e.g. URL) may be provided if resulting image supports linking.

drawPolyline()

drawPolyline([[#Point]]List p, string color, string link)

Given a series of points, the the line that connects them from start to end.  The default color is black.

An optional link (e.g. URL) may be provided if resulting image supports linking.

Public Methods

__init__(self, group_id, imageName, module)

Construct an empty image.

valid()

Query if the current image is valid.

Return bool value: True if valid; False if invalid

Class MAEApp

Super class: MAE

Summary

This class builds on top of the MAE class. It ensures MAE knows that your MAE task is an app and supports it appropriately. An app is a persistent program servicing user requests via UI.

Public Methods

__init__(self, programName, appchannels)

Declare your app MAE instance of this task.

Class MAEConn

Super class: Socket

Summary

This class handles the communication layer between a MAE daemon/app and CommHub.

The challenge that this class faces is that CommHub communicates asynchronously with its client daemons/app, so an app may have sent a DB request (for example) and while wating for the DB response, it may receive some messages, an RPC request, or control message (perhaps initiated by the user).  So, this class has to remember those messages and then process them after the DB response arrives.

Internally, MAEConn discerns these logical communication categories:

• Messages from MsgBroker
• Requests from RpcBroker
• Responses from DbBroker
• Control directives from CommHub (see MAETask class enum TaskComment) such as TaskSuspend, TaskResume, TaskDebug, TaskExit, MAETaskReq, TaskNop, TaskLogRotate,TaskTap

Public Properties

Public Methods

__init__(self, host, port)

Prepare for a TCP socket connection

Return value: instance of Socket to open().  If FALSE, check errno().

writeLine(self, text)

Send text to commhub

Any \n will be converted to text (and later back)

Return bool value:

read(self)

Read any inbound text.

Use its callback (if defined) to process the inbound text.

Return int value: socket status (-1 EOF) - messages ready to be ready (with no callback)

readCommHub(self, wait, rcLineOnly)

Wait for text from commhub.

Read text up to a newline.

Return str value: the string read.  If empty, check errno().

readDB(self, wait, lockoutCallbacks)

Wait for DB response.

Read DB response text up to a newline.

Return str value: the string read.  If empty, check errno().

readMsg(self, wait, queueOk)

Wait for text message.

Read a Message text up to a newline.

Return str value: the string read.  If empty, check errno().

readRpc(self, wait, lockoutCallbacks, queueOk)

Wait for text message.

Read an RPC text up to a newline.

Return str value: the string read.  If empty, check errno().

readyCommHub(self)

Return True if commhub command queue has a command ready to be processed

Return bool value: True if there's 1+ backlog commands

readyDB(self)

Return True if DB command queue has a command ready to be processed

Return bool value: True if there's 1+ backlog commands

readyMsg(self)

Return True if msgbroker message command queue has a command ready to be processed

Return bool value: True if there's 1+ backlog commands

readyRpc(self)

Return True if RPC command queue has a command ready to be processed

Return bool value: True if there's 1+ backlog commands

msgSize(self)

Get size of msg backlog queue

Return int value: size of the queue

dbSize(self)

Get size of db backlog queue

Return int value: size of the queue

rpcSize(self)

Get size of rpc backlog queue

Return int value: size of the queue

setCommHubCB(self, cb, data)

Setup the commhub callback

setDBCB(self, cb, data)

Setup the DB callback

setMsgCB(self, cb, data)

Setup the msgbroker message callback

setRpcCB(self, cb, data)

Setup the RPC request callback

setRpcRespCB(self, cb, data)

Setup the RPC response callback

getMsgCB(self)

Get the msgbroker message callback method

Return value: the msgbroker message callback method

readLine(self, wait, lockoutCallbacks)

Read text up to a newline.

1. Figure out which queue the message is bound for, and push it into that queue.

Return bool value: True if something read

processLine(self, line, lockoutCallbacks)

Put line into right queue or send to callback (if not locked out/blocked)

getCmdCount(self)

of lines received

Return int value:

servicePendingCallbacks(self, includingCommHub)

If any callbacks are configured and data is pending, service them.

Return bool value:

setDbPrefix(self, prefix)

If a different DB prefix is needed, configure new prefix here

setMsgPrefix(self, prefix)

If a different msgbroker message prefix is needed, configure new prefix here

setRpcPrefix(self, prefix)

If a different RPC prefix is needed, configure new prefix here

recordLine(self, send, text)

Save a message out to tap file

setTap(self, tap)

Useful for monitoring all socket communication - a socket tap

will record all read/write activity (set to NULL to disable)

Use msgplayer to replay messages for testing/debugging.

getTap(self)

Query the tap's file pointer

tapActive(self)

Determine if tap is active

Return bool value:

Class MAEDaemon

Super class: MAE

Summary

This class builds on top of the MAE class. It ensures MAE knows that your MAE task is an app and supports it appropriately. A daemon is a persistent program providing support to other MAE tasks.

Public Methods

__init__(self, programName, appchannels)

Declare your daemon MAE instance of this task.

Class MAE

Super class: MAETask

Summary

This class is the starting point of the MAE platform.  Create a single instance for MAE to operate correctly in your main source file. More than likely, you'll instead declare a sub-class - MAEApp, MAEDaemon, or MAEUtility - which is tailored to your tasks's purpose.

Public Properties

Public Methods

__init__(self, module, name, channels)

Constructor for integration with MAE.

setName(name)

Set the MAE task name (with an instance, if non-0). This is the name used to communicate with commhub. The name is often the same as the program's filesystem name, but it is not required to be so.

getName()

Get our MAE task name, including instance if non-0.

Return str value: the MAE task name

getInstance()

Query the instance of this task

Return int value: the instance of the task/app; note that 0 is for the base app

setDaemon()

Declare this task as a daemon - a persistent program providing support to other MAE tasks.

setApp()

Declare this task as an app - a persistent program servicing user requests via UI.

setUtility()

Declare this task as a utility - a one-shot program that performs a task and exits.

isDaemon()

Query if the current task behaves like a daemon.

Return bool value: True if the task is a daemon (because setDaemon() was called), False otherwise.

isApp()

Query if the current task behaves like an app.

Return bool value: True if the task is a daemon (because setApp() was called), False otherwise.

isUtility()

Query if the current task behaves like a utility.

Return bool value: True if the task is a daemon (because setUtility() was called), False otherwise.

init()

MAE calls this when the task environment is setup to let task initialize itself. The Python application needs to define this.

main()

MAE calls this once this task's environment is fully initialized.

This is where your task performs its main functionality.

The Python application needs to define this.

quit(rc, msg)

Either the user or the ecosystem has initiated a task exit. The Python application needs to define this.

dbglog(message)

Output a log message to the debug-only log file - if debug mode is on. When debug mode is off, the message is ignored. The log file is /usr/mae/log/<appname>dbg.log

dbgflush()

This is handy to do just before a program crash to ensure all debug messages have been written to the debug log file. This methods makes sure no messages are in-memory in a buffer, but written to the file.

toggleDebug()

Toggle the debug mode for the program.

Ensures debug.dbgf is pointing to a valid log file, e.g. /usr/mae/log/<taskname>dbg.log

getBroadcast()

Future feature.

Class MAETask

Summary

MAETask is the class used to communicate with CommHub. It sends status and MAE platform commands (such as messages, RPC calls, database queries, global parameter queries). And it handles the responses and commands from CommHub.

Public Properties

Public Methods

__init__()

The constructor

By default, task is not a daemon

By default, task is not managed

init()

An app calls this when the task immediately starts.

This moves the task into 'Initializing' state

If managed and commhub can't run, this will cause exit(227)

Return bool value: Flag: True if connected to CommHub, False if failed to connect

log(text)

Log any messages here (commhub logs them)

dbglog(message)

Output a log message to the debug-only log file - if debug mode is on. When debug mode is off, the message is ignored. The log file is /usr/mae/log/<appname>dbg.log

dbgflush()

This is handy to do just before a program crash to ensure all debug messages have been written to the debug log file. This methods makes sure no messages are in-memory in a buffer, but written to the file.

fd()

This is a file descriptor for select() so the task can monitor for control communication.

Return int value: OS file descriptor of connection to CommHub

isCommHub()

Return True when CommHub is using this class (commhub/MAETask.h returns True)

Return bool value: False for all tasks/apps except commhub.

suspendable(ok)

The daemon app calls this if your daemon is suspendable

if it is not, it will never receive the TaskSuspend command

isSuspended()

Ask if we're currently suspended.

Return bool value: True if current setting is that the task/app can be suspended

pidUpdate(forcePid)

An app calls this after fork()ing to notify CommHub of its new pid.

ok(msg)

The app calls this when the task has finished initializing or to simply report updated run status.

degraded(msg)

The app calls this when the task realizes it is performing suboptimally.

failed(msg)

The app calls this when the task has failed and cannot continue

done(msg)

Call this when the task has completed successfully

setQuit(cbfn)

Setup callback when CommHub sends Quit.

Default action: call exit(0).

setSuspend(cbfn)

Setup callback when CommHub sends Suspend.

Default action: call ignored

setResume(cbfn)

Setup callback when CommHub sends Resume.

Default action: call ignored

setDebug(cbfn)

Setup callback when commhub sends Debug.

Default action: toggle debug_on

fork()

Detach from parent process

process(forever, justone)

Handle events from commhub (perhaps forever) until quit sent. Gets all events or just one event.

openControl(commhubHost)

Connect via TCP to CommHub, the control daemon.

Return bool value: Flag: True upon success False upon failure

controlConnect(startIfNoAnswer, hostname)

Connect to commhub (and start it if we can't connect.

Return bool value: Flag: True upon success False upon failure

controlStart(name)

Start the named daemon

Return bool value: tuple of (success (True/False), status of task after started)

controlStartInstance(name, instanceId)

Return str value: tuple of (success (True/False), status of task after started)

controlStop(name)

Request that CommHub stop the named daemon instance.

Return bool value: Flag: tuple of (success (True/False), status of task after started)

controlSuspend(name)

Request that CommHub suspend the named daemon instance.

Return bool value: tuple of (success (True/False), status of task after started)

controlResume(name)

Request that CommHub resume the named daemon instance.

Return bool value: tuple of (success (True/False), status of task after started)

controlStatus(name)

Get the named daemon's status

Return bool value: tuple of (success (True/False), status of task after started). Status information in the format: <name> <pid> <cluster> <state> <msg>

controlInstances(name)

Get the list of instances for the named daemon

Return bool value: tuple of (success (True/False), list of instances running)

commhubStat(status)

Get CommHub communication statistics.

Return bool value: tuple of (success (True/False), status of task after started)

commhubSpokes(node, status)

Get a list of connected CommHub spokes.

Return bool value: tuple of (success (True/False), list of spokes)

controlStatusName(status)

Get daemon status details

Return str value:

controlStatusPid(status)

Return int value: the task's pid

controlStatusCluster(status)

Return str value:

controlStatusState(status)

Return str value:

controlStatusMsg(status)

Return str value:

controlDebug(name, msg, level)

Request to change the debug mode of the named daemon.

Return bool value: tuple of (Flag: True upon success or False upon failure, status message)

controlTap(name, msg)

Request to tap into the CommHub messages of the named daemon.

Return bool value: tuple of (Flag: True upon success or False upon failure, status message)

controlNewTask(name, msg)

Tell commhub a new task exists

Return bool value: tuple of (Flag: True upon success or False upon failure, status message)

controlDeleteTask(name, msg)

Tell commhub an old task is deleted

Return bool value: tuple of (Flag: True upon success or False upon failure, status message)

controlQuit()

The big STOP button - stop commhub and everything else

Return bool value: tuple of (Flag: True upon success or False upon failure, status message)

controlCommand(cmd)

General method to send a command/request to CommHub.

@Return tuple with two values:

Flag: True if command return code is True, False otherwise return the response from commhub (minus the lead char)

Response from command

Return bool value:

sayHello(daemon, quitIfNoAnswer)

Our first message to CommHub: Declare our identity.

Return bool value: Flag: True if connected to CommHub and CommHub allows our connection

getCommand(wait)

Call this routine to get a CommHub (single keyword) control command from the MAETask.socket.

• Other commands (messages, RPC, DB, etc. are processed and callbacks called.

Return MAECommand value: the command code received, e.g. TaskExit, TaskNop, etc.

getTaskControlArgs()

Get control command arguments

Return str value: the command arguments

setName(newname)

If you want to change the name of this task, use this method

setInstance(newInstance)

Set the instance id for this task (default is 0).

getName()

Query the name of this task.

Return str value: the name of the task/app

getInstance()

Query the instance of this task

Return int value: the instance of the task/app; note that 0 is for the base app

isInstance()

Query if the current task is an instance (versus the base task:

Return bool value: True if the current task is an instance, False if base task

taskBaseName(taskname)

Query the task's name without its instance id.

Return str value: the base task name

setAppId(appid)

Set the app id / messenge channel. Set this before calling init().

getAppId()

Query the app id / message channel in use.

Return str value: the id / message channel

setType(newtype)

FUTURE USE. To change the application type of this task, use this method

setStatus(msg, state, extra)

Set the current status into the database.

Return str value:

setManaged(isManaged)

Configure if this task is managed. (Default: no:

A managed task has status in taskdb

setDaemon(isDaemon)

Configure if this task is a daemon. (Default: no:

A daemon talks to the task manager.

@param isDameon -

isDaemon()

Query if this task is a daemon that runs until told to stop.

Return bool value:

setClusterName(name)

Configure if this task is part of a cluster. (Default: no:

A cluster member is a thread inside a VM

getSystemParameter(parameterName, taskname)

Query a system value for this task (not from data store)

In general, you should need to use this

Return str value:

setSystemParameter(parameterName, parameterValue, taskname)

Set a system value for this task (not from data store)

In general, you should need to use this

Return bool value:

quit(rc, msg)

Quit the service

suspend()

Suspend the service

resume()

Resume the service

toggleTap(_unused)

Toggle message tapping mode

getConfDir()

Get the directory with Configuration files

Return str value: conf directory

getLogDir()

Get the directory with log files

Return str value: log directory

setupAt(triggerTime, cbfn, data, triggerLabel)

Setup a one-time timer event for a specific time point in the future.

Return bool value: True if timer successfully setup

doAfter(delay, cbfn, data, triggerLabel)

Setup a one-time timer event after a delay of specified seconds.

Return bool value: True if timer successfully setup

setupPeriodic(seconds, cbfn, data, triggerLabel)

Setup a time to trigger every so many seconds.

Return bool value: True if timer successfully setup

signalRaised()

Query if a timer has been triggered.

Return bool value: True if a timer has been triggered and not serviced yet

serviceTimer()

Service all outstanding timers

Return int value: the number of timers serviced

getTimerState()

Get the list of future times in a dict.

The key is the triggerLabel, the value is the number of seconds to go before it triggers.

Return dict value: a dict with each trigger's time till it goes off

Class MAEUtility

Super class: MAE

Summary

This class builds on top of the MAE class. It ensures MAE knows that your MAE task is an utility and supports it appropriately. A utility is a one-shot program that performs a task and exits.

Public Methods

__init__(self, programName)

Declare your utility MAE instance of this task.

Class Messenger

Summary

Class to handle MAE (one-way) messages between MAE apps.

Messages are routed by MsgBroker.

This class works in conjunction with the MAETask class, which maintains the connection to CommHub, which is required to reach the MsgBroker daemon.

The MAE class class sets up message channels for your app and code generated by genmae uses this class to send messages.

Public Properties

Public Methods

__init__(self)

Constructor. Connects to app MAETask class instance.

By default, sent messages will be sent on the task's first registered channel.

__del__(self)

Desctructor.  Disconnects from app MAETask class instance.

closeAll()

Close all open channels.

get(channel)

Get Messenger instance of channel

Return value: the instance Messenger registered to the named channel

getChannels()

Get list of all channels open for listening

Return value: a list of all registered channels

open(self, channel, persist, cbfn)

MAE calls this for your app; your app should not call it.

Start listening to a channel.

(Only listen to one channel per instance of Messenger)

Return bool value:

send(self, dest, request, data)

Send a message

Return bool value: True if message sent

sendError(self, dest, errorMessage)

Send an error back to the calling app

Return bool value: True if message sent

close(self)

Close the current channel.

Return bool value:

cease(self)

Close a persistent channel.  MsgBroker will stop queuing messages for this channel.

Return bool value:

mastercb(sock, intext)

Master callback handler for inbound messages

@param text - the message to handle

@param data - callback data

Class

Class MgmtClient

Public Methods

__init__(self)

__init__(self, channel)

setChannel(self, newChannel)

Set the channel name

getChannel(self)

Get the channel name

Return str value: the channel name

addFixedGetParameter(self, category, newParam, fixedValue)

These variables have fixed values

Return bool value:

addGetParameter(self, category, newParam, getFunction)

These variables are provided by function call because they're involved

Return bool value:

addSetParameter(self, category, newParam, setFunction)

Declare the variables that can be changed (after calling respective addGet*()

Return bool value:

getParameter(self, category, qparam)

locate the parameter

Return str value:

parameterExists(self, category, qparam, get)

locate the parameter

Return bool value:

setParameter(self, category, setparam, value)

locate the parameter

Return bool value:

ensureInit(self)

initIntrinsics(self)

getCategories(self, get)

Return list value:

getNames(self, get, category)

handleMesssage(self, cmdparam)

Return bool value:

uptime(self)

Return str value:

incrementInboundRequestCount(self)

Report another inbound message request

incrementInboundBroadcastCount(self)

Report another inbound broadcast message request

incrementInputCount(self)

Report another inbound user response

incrementInboundErrorCount(self)

Report an inbound message that was erroneous

incrementInputErrorCount(self)

Report an inbound user response that could not be processed