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

AME_INITIALISE message

The AME_INITIALISE message is used to initialise a plug-in implemented by a plug-in DLL. Note that only one AME_INITIALISE message will be sent to your DLL, irrespective of the number of plug-ins that it implements.

Parameters

guid

Not used - always NULL.

wParam

This is the version of ANY-maze that is being used. Versions are coded as a DWORD value, with the bytes (high to low) as, for example, 0,4,7,7 for version 4.77. If your plug-in will only work with a certain version of ANY-maze, then you should check this value and return AME_ERROR if the version is inappropriate for your plug-in.

Note that this test can also be performed for each plug-in in your DLL individually, using the wParam of AME_ENUMERATE.

lParam

Handle of the ANY-maze application window.

Return value

The only valid return codes from this message are:

•

AME_OK

•

AME_ERROR

•

AME_NOTIMPLEMENTED (see below)

If initialisation is performed successfully, or you don't need to perform any initialisation, return AME_OK.

If an error occurs, return AME_ERROR. Note that returning AME_ERROR will cause ANY-maze to unload the plug-in DLL and ignore the plug-in entirely (it will be like the DLL doesn't exist).

For compatibility reasons, it is also valid to return AME_NOTIMPLEMENTED, but this is not recommended - even if you perform no initialisation, you should still return AME_OK.

Remarks

In most cases, you can just return AME_OK to this message and do nothing else. However, you may want to take the opportunity to do things like create a thread for your plug-in. Note that you should perform initialisation when you receive this message, and NOT as part of DLL_PROCESS_ATTACH. This is because Windows restricts the operations which can be performed during DLL_PROCESS_ATTACH - see Microsoft's Best Practices for Creating DLLs for full details.

Example code for a DLL which creates a thread as part of initialisation.

case AME_INITIALISE:

//The wParam holds the handle of the main ANY-maze window; note it

hMainWnd = (HWND)wParam;

//Create our thread. If this fails we can't run so return

//AME_ERROR - the plug-in will then be unloaded by ANY-maze

hThread = (HANDLE)_beginthreadex (NULL, 0, MyThreadProc, NULL, 0, NULL);

if (hThread == NULL) {

return AME_ERROR;

}

//We initialised successfully

return AME_OK;

ANY-maze help topic T1006