ANY-maze Help > The ANY-maze reference > ANY-maze plug-ins > Plug-in API reference > AME_TESTSTART message

AME_TESTSTART message

The processing of this message is time critical. Try to avoid any processing which will take more than a few milliseconds to perform.

The AME_TESTSTART message is sent to a plug-in when a test is starting.

Parameters

guid

Pointer to the GUID of the plug-in which is being notified of the test start. All plug-ins that the user has activated (in the protocol) will be sent this message.

If a DLL only implements a single plug-in, it can ignore this parameter - although it is good practice to always check it.

wParam

Size of the AME_TESTDATA record pointed to by lParam, in bytes.

lParam

Pointer to an AME_TESTDATA record. See Remarks section for details.

Return value

The only valid return codes from this message are:

•

AME_OK

•

AME_ERROR

If the message is processed successfully, then return AME_OK.

If an error occurs, return AME_ERROR. Note that doing so will mean that the plug-in is excluded from the test, i.e. no AME_POSN messages will be sent to it, nor will it receive an AME_TESTEND or AME_TESTABORT message at the end of the test. Thus on failure, you should perform all necessary cleaning-up (for example freeing memory) before returning.

Remarks

A plug-in should use this message to initialise itself ready for a test. The AME_TESTDATA record includes a pointer to a Settings buffer, which will hold the settings for the test. These may be uninitialised (filled with zeros), in which case the plug-in should detect this and use default values.

As part of the processing of this message, the plug-in should allocate a record in which it will store all the data it needs in order to process the test - this will be the plug-in's 'Context record'.

If there is any data passed in the AME_TESTDATA record (such as settings) which the plug-in will need during the processing of the test, then it should copy this data to its context record.

If the plug-in will require any 'static' variables for its processing, then it should include these in its context record too. For example, if the plug-in will be determining the state of something, it will probably want to record the 'Current' state in the context record. Don't use static variables in the processing of AME_TESTSTART, AME_POSN, AME_TESTEND or AME_TESTABORT messages, as this processing must be thread-safe.

A pointer to the context record should be passed back to ANY-maze in the AME_TESTDATA->Context field.

Remember, ANY-maze is multi-threaded and your plug-in may be used to analyse data from multiple tests all running simultaneously. By recording everything about the analysis of a test in a context record, you avoid having to worry (very much) about multi-threading issues, as ANY-maze will simply pass the correct context for a test to your plug-in in each AME_POSN and AME_TESTEND or AME_TESTABORT message.

Below is an example of the processing for this message:

case AME_TESTSTART:

//The lParam points at a AME_TESTDATA record and the wParam is the

//size of the record. Check the size

assert (wParam >= sizeof(AME_TESTDATA));

if (wParam < sizeof(AME_TESTDATA)) return AME_ERROR;

//Access the AME_TESTDATA record

AME_TestData = (LPAME_TESTDATA)lParam;

//Allocate our context record - if this fails return AME_ERROR

MyPlugInContextRec = new MYPLUGINCONTEXTREC;

if (MyPlugInContextRec == NULL) return AME_ERROR;

//The passed AME_TestData record includes a pointer to the settings

//for this analysis. Check whether they are initialised and if not

//set defaults

Settings = (LPMYPLUGINSETTINGS)AME_TestData->Settings;

if (!Settings->Initialised) SetDefaultSettings (Settings);

//Note the settings in the context record

MyPlugInContextRec->Settings = *Settings;

//Initialise other fields of the context record ready for analysis

//.... exactly what you'll do here depends on your implementation.....

//Return the address of MyPlugInContextRec so that ANY-maze can pass it

//back to us in AME_POSN messages

AME_TestData->Context = (LPVOID)MyPlugInContextRec;

return AME_OK;

ANY-maze help topic T1017