From d67a5162addcc143c870ed35000212bdd7d7ab2c Mon Sep 17 00:00:00 2001 From: Paul Gilbert Date: Fri, 18 May 2012 21:48:03 +1000 Subject: TONY: Converting method comments to DOXYGEN format --- engines/tony/mpal/mpal.cpp | 770 +++++++++++++++------------------------------ engines/tony/mpal/mpal.h | 705 +++++++++++++++-------------------------- 2 files changed, 503 insertions(+), 972 deletions(-) diff --git a/engines/tony/mpal/mpal.cpp b/engines/tony/mpal/mpal.cpp index f049ecf3ea..a173b707f2 100644 --- a/engines/tony/mpal/mpal.cpp +++ b/engines/tony/mpal/mpal.cpp @@ -61,6 +61,8 @@ namespace Tony { namespace MPAL { +#define GETARG(type) va_arg(v, type) + /****************************************************************************\ * Copyright \****************************************************************************/ @@ -76,39 +78,25 @@ const char *mpalCopyright = * Internal functions \****************************************************************************/ -/****************************************************************************\ -* -* Function: void LockVar(void); -* -* Description: Locka le variabili per accederci -* -\****************************************************************************/ - +/** + * Locks the variables for access + */ void LockVar(void) { GLOBALS.lpmvVars = (LPMPALVAR)GlobalLock(GLOBALS.hVars); } -/****************************************************************************\ -* -* Function: void UnlockVar(void); -* -* Description: Unlocka le variabili dopo l'uso -* -\****************************************************************************/ +/** + * Unlocks variables after use + */ void UnlockVar(void) { GlobalUnlock(GLOBALS.hVars); } -/****************************************************************************\ -* -* Function: void LockMsg(void); -* -* Description: Locka i messaggi per accederci -* -\****************************************************************************/ - +/** + * Locks the messages for access + */ static void LockMsg(void) { #ifdef NEED_LOCK_MSGS GLOBALS.lpmmMsgs = (LPMPALMSG)GlobalLock(GLOBALS.hMsgs); @@ -116,14 +104,9 @@ static void LockMsg(void) { } -/****************************************************************************\ -* -* Function: void UnlockMsg(void); -* -* Description: Unlocka i messaggi dopo l'uso -* -\****************************************************************************/ - +/** + * Unlocks the messages after use + */ static void UnlockMsg(void) { #ifdef NEED_LOCK_MSGS GlobalUnlock(GLOBALS.hMsgs); @@ -131,125 +114,79 @@ static void UnlockMsg(void) { } -/****************************************************************************\ -* -* Function: void LockDialogs(void); -* -* Description: Locka i dialoghi per accederci -* -\****************************************************************************/ - +/** + * Locks the dialogs for access + */ static void LockDialogs(void) { GLOBALS.lpmdDialogs = (LPMPALDIALOG)GlobalLock(GLOBALS.hDialogs); } -/****************************************************************************\ -* -* Function: void UnlockDialogs(void); -* -* Description: Unlocka i dialoghi dopo l'uso -* -\****************************************************************************/ - +/** + * Unlocks the dialogs after use + */ static void UnlockDialogs(void) { GlobalUnlock(GLOBALS.hDialogs); } -/****************************************************************************\ -* -* Function: void LockLocations(void); -* -* Description: Locka le strutture di dati sulle locazioni -* -\****************************************************************************/ - +/** + * Locks the location data structures for access + */ static void LockLocations(void) { GLOBALS.lpmlLocations = (LPMPALLOCATION)GlobalLock(GLOBALS.hLocations); } -/****************************************************************************\ -* -* Function: void UnlockLocations(void); -* -* Description: Unlocka le strutture di dati sulle locazioni -* -\****************************************************************************/ - +/** + * Unlocks the location structures after use + */ static void UnlockLocations(void) { GlobalUnlock(GLOBALS.hLocations); } -/****************************************************************************\ -* -* Function: void LockItems(void); -* -* Description: Locka le strutture di dati sugli item -* -\****************************************************************************/ - +/** + * Locks the items structures for use + */ static void LockItems(void) { GLOBALS.lpmiItems = (LPMPALITEM)GlobalLock(GLOBALS.hItems); } -/****************************************************************************\ -* -* Function: void UnlockItems(void); -* -* Description: Unlocka le strutture di dati sugli item -* -\****************************************************************************/ - +/** + * Unlocks the items structures after use + */ static void UnlockItems(void) { GlobalUnlock(GLOBALS.hItems); } -/****************************************************************************\ -* -* Function: void LockScripts(void); -* -* Description: Locka le strutture di dati sugli script -* -\****************************************************************************/ +/** + * Locks the script data structures for use + */ static void LockScripts(void) { GLOBALS.lpmsScripts = (LPMPALSCRIPT)GlobalLock(GLOBALS.hScripts); } -/****************************************************************************\ -* -* Function: void UnlockScripts(void); -* -* Description: Unlocka le strutture di dati sugli script -* -\****************************************************************************/ - +/** + * Unlocks the script data structures after use + */ static void UnlockScripts(void) { GlobalUnlock(GLOBALS.hScripts); } -/****************************************************************************\ -* -* Function: int varGetValue(char * lpszVarName); -* -* Description: Restituisce il valore corrente di una variabile globale -* -* Input: char * lpszVarName Nome della variabile -* -* Return: Valore corrente -* -* Note: Prima di questa funzione, bisogna richiamare LockVar() che -* locka le variabili globali per l'utilizzo. Dopo inoltre bi- -* sogna ricordarsi di chiamare UnlockVar() -* -\****************************************************************************/ - +/** + * Returns the current value of a global variable + * + * @param lpszVarName Name of the variable + * @returns Current value + * @remarks Before using this method, you must call LockVar() to + * lock the global variablves for use. Then afterwards, you will + * need to remember to call UnlockVar() + */ int32 varGetValue(const char *lpszVarName) { int i; LPMPALVAR v=GLOBALS.lpmvVars; @@ -263,17 +200,11 @@ int32 varGetValue(const char *lpszVarName) { } -/****************************************************************************\ -* -* Function: void varSetValue(char * lpszVarName, int val); -* -* Description: Setta un nuovo valore per una variabile globale di MPAL -* -* Input: char * lpszVarName Nome della variabile -* int val Valore da settare -* -\****************************************************************************/ - +/** + * Sets the value of a MPAL global variable + * @param lpszVarName Name of the variable + * @param val Value to set + */ void varSetValue(const char *lpszVarName, int32 val) { uint i; LPMPALVAR v = GLOBALS.lpmvVars; @@ -298,22 +229,14 @@ void varSetValue(const char *lpszVarName, int32 val) { } -/****************************************************************************\ -* -* Function: int locGetOrderFromNum(uint32 nLoc); -* -* Description: Trova l'indice della locazione #nLoc all'interno dell'array -* delle strutture delle locazioni -* -* Input: uint32 nLoc Numero della locazione da cercare -* -* Return: Indice, o -1 se la locazione non e' presente -* -* Note: Per funzionare, la funzione necessita che le locazioni siano -* state lockate con LockLoc() -* -\****************************************************************************/ - +/** + * Find the index of a location within the location array. Remember to call LockLoc() beforehand. + * + * @param nLoc Location number to search for + * @returns Index, or -1 if the location is not present + * @remarks This function requires the location list to have + * first been locked with a call to LockLoc(). + */ static int locGetOrderFromNum(uint32 nLoc) { int i; LPMPALLOCATION loc = GLOBALS.lpmlLocations; @@ -325,22 +248,14 @@ static int locGetOrderFromNum(uint32 nLoc) { return -1; } -/****************************************************************************\ -* -* Function: int msgGetOrderFromNum(uint32 nMsg); -* -* Description: Trova l'indice del messaggio #nMsg all'interno dell'array -* delle strutture dei messaggi -* -* Input: uint32 nMsg Numero del messaggio da cercare -* -* Return: Indice, o -1 se il messaggio non e' presente -* -* Note: Per funzionare, la funzione necessita che i messaggi siano -* stati lockati con LockMsg() -* -\****************************************************************************/ +/** + * Find the index of a message within the messages array + * @param nMsg Message number to search for + * @returns Index, or -1 if the message is not present + * @remarks This function requires the message list to have + * first been locked with a call to LockMsg() + */ static int msgGetOrderFromNum(uint32 nMsg) { int i; LPMPALMSG msg = GLOBALS.lpmmMsgs; @@ -352,23 +267,13 @@ static int msgGetOrderFromNum(uint32 nMsg) { return -1; } - -/****************************************************************************\ -* -* Function: int itemGetOrderFromNum(uint32 nItem); -* -* Description: Trova l'indice dell'item #nItem all'interno dell'array delle -* strutture degli item -* -* Input: uint32 nItem Numero dell'item da cercare -* -* Return: Indice, o -1 se l'item non e' presente -* -* Note: Per funzionare, questa funzione necessita che gli item siano -* stati lockati tramite LockItem() -* -\****************************************************************************/ - +/** + * Find the index of an item within the items array + * @param nItem Item number to search for + * @returns Index, or -1 if the item is not present + * @remarks This function requires the item list to have + * first been locked with a call to LockItems() + */ static int itemGetOrderFromNum(uint32 nItem) { int i; LPMPALITEM item = GLOBALS.lpmiItems; @@ -381,22 +286,13 @@ static int itemGetOrderFromNum(uint32 nItem) { } -/****************************************************************************\ -* -* Function: int scriptGetOrderFromNum(uint32 nScript); -* -* Description: Trova l'indice dello script #nScript all'interno dell'array -* delle strutture degli script -* -* Input: uint32 nScript Numero dello script da cercare -* -* Return: Indice, o -1 se lo script non e' presente -* -* Note: Per funzionare, questa funzione necessita che gli script siano -* stati lockati tramite LockScript() -* -\****************************************************************************/ - +/** + * Find the index of a script within the scripts array + * @param nScript Script number to search for + * @returns Index, or -1 if the script is not present + * @remarks This function requires the script list to have + * first been locked with a call to LockScripts() + */ static int scriptGetOrderFromNum(uint32 nScript) { int i; LPMPALSCRIPT script = GLOBALS.lpmsScripts; @@ -409,22 +305,13 @@ static int scriptGetOrderFromNum(uint32 nScript) { } -/****************************************************************************\ -* -* Function: int dialogGetOrderFromNum(uint32 nDialog); -* -* Description: Trova l'indice del dialog #nDialog all'interno dell'array -* delle strutture dei dialog -* -* Input: uint32 nDialog Numero del dialog da cercare -* -* Return: Indice, o -1 se il dialog non e' presente -* -* Note: Per funzionare, questa funzione necessita che i dialog siano -* stati lockati tramite LockDialogs() -* -\****************************************************************************/ - +/** + * Find the index of a dialog within the dialogs array + * @param nDialog Dialog number to search for + * @returns Index, or -1 if the dialog is not present + * @remarks This function requires the dialog list to have + * first been locked with a call to LockDialogs() + */ static int dialogGetOrderFromNum(uint32 nDialog) { int i; LPMPALDIALOG dialog = GLOBALS.lpmdDialogs; @@ -437,21 +324,12 @@ static int dialogGetOrderFromNum(uint32 nDialog) { } - -/****************************************************************************\ -* -* Function: char * DuplicateMessage(uint32 nMsgOrd); -* -* Description: Duplica un messaggio -* -* Input: uint32 nMsgOrd Indice del messaggio dentro l'array -* di strutture dei messaggi -* -* Return: Pointer al messaggio duplicato (che puo' essere liberato -* con GlobalFree()). -* -\****************************************************************************/ - +/** + * Duplicates a message + * @param nMsgOrd Index of the message inside the messages array + * @returns Pointer to the duplicated message. + * @remarks Remember to free the duplicated message when done with it. + */ static char *DuplicateMessage(uint32 nMsgOrd) { const char *origmsg; char *clonemsg; @@ -478,22 +356,13 @@ static char *DuplicateMessage(uint32 nMsgOrd) { } -/****************************************************************************\ -* -* Function: char * DuplicateDialogPeriod(uint32 nDlgOrd, uint32 nPeriod); -* -* Description: Duplica una frase di un dialog -* -* Input: uint32 nDlgOrd Indice del dialogo dentro l'array di -* strutture dei dialoghi -* -* uint32 nPeriod Numero della frase da duplicare -* -* Return: Pointer alla frase duplicata (che puo' essere liberata con -* GlobalFree()). -* -\****************************************************************************/ - +/** + * Duplicate a sentence of a dialog + * @param nDlgOrd Index of the dialog in the dialogs array + * @param nPeriod Sentence number to be duplicated. + * @returns Pointer to the duplicated phrase. Remember to free it + * when done with it. + */ static char *DuplicateDialogPeriod(uint32 nPeriod) { const char *origmsg; char *clonemsg; @@ -524,19 +393,12 @@ static char *DuplicateDialogPeriod(uint32 nPeriod) { } - -/****************************************************************************\ -* -* Function: HGLOBAL resLoad(uint32 dwId); -* -* Description: Carica una risorsa dal file MPR -* -* Input: uint32 dwId ID della risorsa da caricare -* -* Return: Handle alla memoria in cui si trova la risorsa -* -\****************************************************************************/ - +/** + * Load a resource from the MPR file + * + * @param dwId ID of the resource to load + * @returns Handle to the loaded resource + */ HGLOBAL resLoad(uint32 dwId) { int i; HGLOBAL h; @@ -736,21 +598,13 @@ static LPITEM GetItemData(uint32 nOrdItem) { } -/****************************************************************************\ -* -* Function: void CustomThread(LPCFCALL p); -* -* Description: Thread che richiama una funzione custom. Viene usato negli -* script, in modo che ciascuna funzione venga eseguita senza -* ritardare le altre -* -* Input: LPCFCALL p Struttura che definisce la chiamata -* -* Note: La struttura passata come parametro viene freeata con -* GlobalFree() alla fine dell'esecuzione. -* -\****************************************************************************/ - +/** + * Thread that calls a custom function. It is used in scripts, so that each script + * function is executed without delaying the others. + * + * @param param pointer to a pointer to the structure that defines the call. + * @remarks The passed structure is freed when the process finishes. + */ void CustomThread(CORO_PARAM, const void *param) { CORO_BEGIN_CONTEXT; LPCFCALL p; @@ -768,20 +622,12 @@ void CustomThread(CORO_PARAM, const void *param) { } -/****************************************************************************\ -* -* Function: void ScriptThread(LPMPALSCRIPT s); -* -* Description: Esegue uno script. Questa funzione e' pensata come starting -* point per un thread -* -* Input: LPMPALSCRIPT s Script da eseguire -* -* Note: Lo script passato come parametro viene, alla fine dell'ese- -* cuzione, freeato con una GlobalFree() -* -\****************************************************************************/ - +/** + * Main process for running a script. + * + * @param param Pointer to a pointer to a structure containing the script data. + * @remarks The passed structure is freed when the process finishes. + */ void ScriptThread(CORO_PARAM, const void *param) { CORO_BEGIN_CONTEXT; uint i, j, k; @@ -866,20 +712,13 @@ void ScriptThread(CORO_PARAM, const void *param) { } -/****************************************************************************\ -* -* Function: void ActionThread(LPMPALITEM item); -* -* Description: Thread che esegue una azione su un item. Il thread -* esegue sempre l'azione 0, per cui e' necessario creare -* un item nuovo in cui l'azione 0 sia quella richiesta. -* Inoltre non viene controllata l'espressione when, ma viene -* sempre eseguita l'azione. -* -* Input: LPMPALITEM item Item che contiene l'azione -* -\****************************************************************************/ - +/** + * Thread that performs an action on an item. the thread always executes the action, + * so it should create a new item in which the action is the one required. + * Furthermore, the expression is not checked, but it is always performed the action. + * + * @param param Pointer to a pointer to a structure containing the action. + */ void ActionThread(CORO_PARAM, const void *param) { // COROUTINE CORO_BEGIN_CONTEXT; @@ -935,8 +774,8 @@ void ActionThread(CORO_PARAM, const void *param) { /** * This thread monitors a created action to detect when it ends. - * @remarks Since actions can spawn sub-actions, this needs to be a - * separate thread to determine when the outer action is done + * @remarks Since actions can spawn sub-actions, this needs to be a + * separate thread to determine when the outer action is done */ void ShutUpActionThread(CORO_PARAM, const void *param) { // COROUTINE @@ -956,18 +795,12 @@ void ShutUpActionThread(CORO_PARAM, const void *param) { CORO_END_CODE; } -/****************************************************************************\ -* -* Function: void LocationPollThread(uint32 id); -* -* Description: Esegue il polling di una locazione (starting point di un -* thread). -* -* Input: uint32 id Indice per gli array relativi ai -* polling degli item delle locazioni -* -\****************************************************************************/ +/** + * Polls one location (starting point of a process) + * + * @param param Pointer to an index in the array of polling locations. + */ void LocationPollThread(CORO_PARAM, const void *param) { typedef struct { uint32 nItem, nAction; @@ -1257,22 +1090,17 @@ void LocationPollThread(CORO_PARAM, const void *param) { -/****************************************************************************\ -* -* Function: void ShutUpDialogThread(HANDLE hThread); -* -* Description: Aspetta la fine dell'esecuzione del dialog thread e ripri- -* stina le variabili globali indicando che il dialogo e' finito. -* -* Input: HANDLE hThread Handle del dialog thread -* -* Note: Si ricorre a questo thread aggiuntivo, al posto di azzerare -* le variabili all'interno del dialog thread stesso, poiche', -* a causa della natura ricorsiva di un dialogo, non e' sempre -* possibile sapere quando esattamente finisce un dialogo. -* -\****************************************************************************/ + +/** + * Wait for the end of the dialog execution thread, and then restore global + * variables indicating that the dialogue has finished. + * + * @param param Pointer to a handle to the dialog + * @remarks This additional process is used, instead of clearing variables + * within the same dialog thread, because due to the recursive nature of a dialog, + * it would be difficult to know within it when the dialog is actually ending. + */ void ShutUpDialogThread(CORO_PARAM, const void *param) { CORO_BEGIN_CONTEXT; CORO_END_CONTEXT(_ctx); @@ -1296,9 +1124,10 @@ void ShutUpDialogThread(CORO_PARAM, const void *param) { void DoChoice(CORO_PARAM, uint32 nChoice); + /** * Executes a group of the current dialog. Can 'be the Starting point of a process. - * @parm nGroup Number of the group to perform + * @parm nGroup Number of the group to perform */ void GroupThread(CORO_PARAM, const void *param) { CORO_BEGIN_CONTEXT; @@ -1371,16 +1200,11 @@ void GroupThread(CORO_PARAM, const void *param) { } -/****************************************************************************\ -* -* Function: void DoChoice(uint32 nChoice); -* -* Description: Esegue una scelta nel dialogo corrente -* -* Input: uint32 nChoice Numero della scelta da eseguire -* -\****************************************************************************/ - +/** + * Make a choice in the current dialog. + * + * @param nChoice Number of choice to perform + */ void DoChoice(CORO_PARAM, uint32 nChoice) { CORO_BEGIN_CONTEXT; LPMPALDIALOG dialog; @@ -1476,29 +1300,18 @@ void DoChoice(CORO_PARAM, uint32 nChoice) { } - -/****************************************************************************\ -* -* Function: HANDLE DoAction(uint32 nAction, uint32 ordItem, uint32 dwParam); -* -* Description: Esegue una azione su un certo item -* -* Input: uint32 nAction Numero dell'azione -* uint32 ordItem Indice dell'item nelle strutture -* degli item -* uint32 dwParam Eventuale parametro per l'azione -* -* Return: Handle del thread che sta eseguendo l'azione, oppure -* CORO_INVALID_PID_VALUE se l'azione non e' definita, o l'item -* e' disattivato. -* -* Note: Si puo' ottenere l'indice dell'item a partire dal suo numero -* tramite la funzione itemGetOrderFromNum(). -* Gli item devono essere lockati, perche' questa funzione -* funzioni, tramite LockItem(); -* -\****************************************************************************/ - +/** + * Perform an action on a certain item. + * + * @param nAction Action number + * @param ordItem Index of the item in the items list + * @param dwParam Any parameter for the action. + * @returns Id of the process that was launched to perform the action, or + * CORO_INVALID_PID_VALUE if the action was not defined, or the item was inactive. + * @remarks You can get the index of an item from it's number by using + * the itemGetOrderFromNum() function. The items list must first be locked + * by calling LockItem(). + */ static uint32 DoAction(uint32 nAction, uint32 ordItem, uint32 dwParam) { LPMPALITEM item = GLOBALS.lpmiItems; int i; @@ -1594,20 +1407,14 @@ static uint32 DoDialog(uint32 nDlgOrd, uint32 nGroup) { } -/****************************************************************************\ -* -* Function: bool DoSelection(uint32 nChoice, uint32 dwData); -* -* Description: Prende nota del select scelto dall'utente, e avverte il -* thread che stava eseguendo il dialogo che puo' continuare. -* -* Input: uint32 nChoice Numero della scelta che era in corso -* uint32 dwData Dato abbinato al select selezionato -* -* Return: true se tutto OK, false in caso di errore -* -\****************************************************************************/ - +/** + * Takes note of the selection chosen by the user, and warns the process that was running + * the box that it can continue. + * + * @param nChoice Number of choice that was in progress + * @param dwData Since combined with select selection + * @returns True if everything is OK, false on failure + */ bool DoSelection(uint32 i, uint32 dwData) { LPMPALDIALOG dialog=GLOBALS.lpmdDialogs+GLOBALS.nExecutingDialog; int j; @@ -1625,30 +1432,18 @@ bool DoSelection(uint32 i, uint32 dwData) { } +/** + * @defgroup Exported functions + */ -/****************************************************************************\ -* Exported functions -\****************************************************************************/ - -/****************************************************************************\ -* -* Function: bool mpalInit(LPSTR lpszMpcFileName, LPSTR lpszMprFileName, -* LPLPCUSTOMFUNCTION lplpcfArray); -* -* Description: Inizializza la libreria MPAL, e apre un file .MPC, che -* verra' utilizzato per tutte le query -* -* Input: char * lpszMpcFileName Nome del file .MPC, comprensivo di -* estensione -* char * lpszMprFileName Nome del file .MPR, comprensivo di -* estensione -* LPLPCUSTOMFUNCTION -* lplpcfArray Array di pointer a funzioni custom -* -* Return: true se tutto OK, false in caso di errore -* -\****************************************************************************/ - +/** + * Initialises the MPAL library and opens the .MPC file, which will be used for all queries. + * + * @param lpszMpcFileName Name of the MPC file + * @param lpszMprFileName Name of the MPR file + * @param lplpcfArray Array of pointers to custom functions. + * @returns True if everything is OK, false on failure + */ bool mpalInit(const char *lpszMpcFileName, const char *lpszMprFileName, LPLPCUSTOMFUNCTION lplpcfArray, Common::String *lpcfStrings) { Common::File hMpc; @@ -1803,34 +1598,15 @@ bool mpalInit(const char *lpszMpcFileName, const char *lpszMprFileName, return true; } -/****************************************************************************\ -* -* Function: uint32 mpalQuery(uint16 wQueryType, ...); -* -* Description: Questa e' la funzione generale per comunicare con la libreria, -* per richiedere informazioni riguardo a quanto si trova nel -* file .MPC -* -* Input: uint16 wQueryType Tipo di query. La lista e' in -* enum QueryTypes -* -* Return: 4 bytes che dipendono dal tipo di query -* -* Note: E' _FORTEMENTE_ consigliato utilizzare le macro -* definite sopra per utilizzare le query, dato che -* permettono di evitare spiacevoli bug dovuti a dimenticanze -* di parametri. -* -\****************************************************************************/ - -#define GETARG(type) va_arg(v, type) /** - * MPAL Query variation #1 - dword return - * This variation handles mpal query types that need to return a dword result. + * This is a general function to communicate with the library, to request information + * about what is in the .MPC file * - * @param wQueryType Query type - * @param v Variable length argument list + * @param wQueryType Type of query. The list is in the QueryTypes enum. + * @returns 4 bytes depending on the type of query + * @remarks This is the specialised version of the original single mpalQuery + * method that returns numeric results. */ uint32 mpalQueryDWORD(uint16 wQueryType, ...) { int x, y, z; @@ -1844,6 +1620,7 @@ uint32 mpalQueryDWORD(uint16 wQueryType, ...) { GLOBALS.mpalError = OK; if (wQueryType == MPQ_VERSION) { + /* * uint32 mpalQuery(MPQ_VERSION); */ @@ -2021,11 +1798,13 @@ uint32 mpalQueryDWORD(uint16 wQueryType, ...) { } /** - * MPAL Query variation #1 - dword return - * This variation handles mpal query types that need to return a pointer/handle result + * This is a general function to communicate with the library, to request information + * about what is in the .MPC file * - * @param wQueryType Query type - * @param v Variable length argument list + * @param wQueryType Type of query. The list is in the QueryTypes enum. + * @returns 4 bytes depending on the type of query + * @remarks This is the specialised version of the original single mpalQuery + * method that returns a pointer or handle. */ HANDLE mpalQueryHANDLE(uint16 wQueryType, ...) { int x, y; @@ -2176,13 +1955,15 @@ HANDLE mpalQueryHANDLE(uint16 wQueryType, ...) { return hRet; } + /** - * MPAL Query variation #1 - dword return - * This variation handles mpal query types that need to return a pointer/handle result + * This is a general function to communicate with the library, to request information + * about what is in the .MPC file * - * @param wQueryType Query type - * @param dwRet DWORD return value (when coroutine method completes) - * @param v Variable length argument list + * @param wQueryType Type of query. The list is in the QueryTypes enum. + * @returns 4 bytes depending on the type of query + * @remarks This is the specialised version of the original single mpalQuery + * method that needs to run within a co-routine context. */ void mpalQueryCORO(CORO_PARAM, uint16 wQueryType, uint32 *dwRet, ...) { CORO_BEGIN_CONTEXT; @@ -2216,34 +1997,22 @@ void mpalQueryCORO(CORO_PARAM, uint16 wQueryType, uint32 *dwRet, ...) { } -/****************************************************************************\ -* -* Function: uint32 mpalGetError(void); -* -* Description: Ritorna il codice di errore corrente di MPAL -* -* Return: Codice di errore -* -\****************************************************************************/ - +/** + * Returns the current MPAL error code + * + * @returns Error code + */ uint32 mpalGetError(void) { return GLOBALS.mpalError; } -/****************************************************************************\ -* -* Function: void mpalExecuteScript(int nScript); -* -* Description: Esegue uno script. Lo script viene eseguito in multitasking -* tramite un thread. -* -* Input: int nScript Numero dello script da eseguire -* -* Return: true se lo script e' stato avviato, false in caso di errore -* -\****************************************************************************/ - +/** + * Execute a script. The script runs on multitasking by a thread. + * + * @param nScript Script number to run + * @returns TRUE if the script 'was launched, FALSE on failure + */ bool mpalExecuteScript(int nScript) { int n; LPMPALSCRIPT s; @@ -2265,38 +2034,26 @@ bool mpalExecuteScript(int nScript) { } -/****************************************************************************\ -* -* Function: void mpalInstallItemIrq(LPITEMIRQFUNCTION GLOBALS.lpiifCustom); -* -* Description: Install a custom routine that will be called by MPAL every -* time the pattern of an item has been changed. -* -* Input: LPITEMIRQFUNCTION GLOBALS.lpiifCustom Custom function to install -* -\****************************************************************************/ - +/** + * Install a custom routine That will be called by MPAL every time the pattern + * of an item has been changed. + * + * @param lpiifCustom Custom function to install + */ void mpalInstallItemIrq(LPITEMIRQFUNCTION lpiifCus) { GLOBALS.lpiifCustom = lpiifCus; } -/****************************************************************************\ -* -* Function: bool mpalStartIdlePoll(int nLoc); -* -* Description: Process the idle actions of the items on one location. -* -* Input: int nLoc Number of the location whose items -* must be processed for idle actions. -* -* Return: true se tutto OK, false se si e' superato il limite massimo. -* -* Note: Il numero massimo delle locazione che e' possibile pollare -* contemporaneamente e' contenuto nel define MAXPOLLINGFUNCIONS -* -\****************************************************************************/ - +/** + * Process the idle actions of the items on one location. + * + * @param nLoc Number of the location whose items must be processed + * for idle actions. + * @returns TRUE if all OK, and FALSE if it exceeded the maximum limit. + * @remarks The maximum number of locations that can be polled + * simultaneously is defined defined by MAXPOLLINGFUNCIONS + */ bool mpalStartIdlePoll(int nLoc) { uint32 i; @@ -2322,20 +2079,13 @@ bool mpalStartIdlePoll(int nLoc) { } - -/****************************************************************************\ -* -* Function: bool mpalEndIdlePoll(int nLoc); -* -* Description: Stop processing the idle actions of the items on one location. -* -* Input: int nLoc Number of the location -* -* Return: true se tutto OK, false se la locazione specificata non era -* in fase di polling -* -\****************************************************************************/ - +/** + * Stop processing the idle actions of the items on one location. + * + * @param nLo Number of the location + * @returns TRUE if all OK, FALSE if the specified location was not + * in the process of polling + */ void mpalEndIdlePoll(CORO_PARAM, int nLoc, bool *result) { CORO_BEGIN_CONTEXT; int i; @@ -2365,33 +2115,22 @@ void mpalEndIdlePoll(CORO_PARAM, int nLoc, bool *result) { } - -/****************************************************************************\ -* -* Function: int mpalGetSaveStateSize(void); -* -* Description: Acquire the length of a save state -* -* Return: Length in bytes -* -\****************************************************************************/ - +/** + * Retrieve the length of a save state + * + * @returns Length in bytes + */ int mpalGetSaveStateSize(void) { return GLOBALS.nVars * sizeof(MPALVAR) + 4; } -/****************************************************************************\ -* -* Function: void mpalSaveState(byte *buf); -* -* Description: Store the save state into a buffer. The buffer must be -* length at least the size specified with mpalGetSaveStateSize -* -* Input: byte *buf Buffer where to store the state -* -\****************************************************************************/ - +/** + * Store the save state into a buffer. The buffer must be + * length at least the size specified with mpalGetSaveStateSize + * + * @param buf Buffer where to store the state + */ void mpalSaveState(byte *buf) { LockVar(); WRITE_LE_UINT32(buf, GLOBALS.nVars); @@ -2399,18 +2138,13 @@ void mpalSaveState(byte *buf) { UnlockVar(); } -/****************************************************************************\ -* -* Function: int mpalLoadState(byte *buf); -* -* Description: Load a save state from a buffer. -* -* Input: byte *buf Buffer where to store the state -* -* Return: Length of the state in bytes -* -\****************************************************************************/ +/** + * Load a save state from a buffer. + * + * @param buf Buffer where to store the state + * @returns Length of the state buffer in bytes + */ int mpalLoadState(byte *buf) { // Dobbiamo distruggere tutte le variabili e ricrearle GlobalFree(GLOBALS.hVars); diff --git a/engines/tony/mpal/mpal.h b/engines/tony/mpal/mpal.h index 319f71c6a8..a14bfd1895 100644 --- a/engines/tony/mpal/mpal.h +++ b/engines/tony/mpal/mpal.h @@ -126,6 +126,12 @@ namespace Tony { namespace MPAL { +/****************************************************************************\ +* Type definitions +\****************************************************************************/ + +typedef void *HANDLE; + /****************************************************************************\ * Macro definitions and structures \****************************************************************************/ @@ -140,25 +146,19 @@ namespace MPAL { #define LPSTR char * -/****************************************************************************\ -* enum QueryCoordinates -* --------------------- -* Description: Macro for use with queries that may refer to X and Y co-ordinates -\****************************************************************************/ - +/** + * Macro for use with queries that may refer to X and Y co-ordinates + */ enum QueryCoordinates { MPQ_X, MPQ_Y }; -/****************************************************************************\ -* enum QueryTypes -* --------------- -* Description: Query can be used with mpalQuery methods. In practice corresponds -* all claims that can do at the library -\****************************************************************************/ - +/** + * Query can be used with mpalQuery methods. In practice corresponds all claims + * that can do at the library + */ enum QueryTypes { /* General Query */ MPQ_VERSION=10, @@ -189,13 +189,9 @@ enum QueryTypes { MPQ_DO_DIALOG }; - -/****************************************************************************\ -* typedef ITEM -* ------------ -* Description: Framework to manage the animation of an item -\****************************************************************************/ - +/** + * Framework to manage the animation of an item + */ typedef struct { char *frames[MAXFRAMES]; Common::Rect frameslocations[MAXFRAMES]; @@ -214,311 +210,188 @@ typedef struct { typedef ITEM *LPITEM; -/****************************************************************************\ -* typedef LPCUSTOMFUNCTION -* ------------------------ -* Description: Define a custom function, to use the language MPAL -* to perform various controls as a result of an action -\****************************************************************************/ - +/** + * Define a custom function, to use the language MPAL to perform various controls as a result of an action + */ typedef void (*LPCUSTOMFUNCTION)(CORO_PARAM, uint32, uint32, uint32, uint32); typedef LPCUSTOMFUNCTION *LPLPCUSTOMFUNCTION; - -/****************************************************************************\ -* typedef LPITEMIRQFUNCTION -* ------------------------- -* Description: Define an IRQ of an item that is called when the -* pattern changes or the status of an item -\****************************************************************************/ - +/** + * + * Define an IRQ of an item that is called when the pattern changes or the status of an item + */ typedef void (*LPITEMIRQFUNCTION)(uint32, int, int); typedef LPITEMIRQFUNCTION* LPLPITEMIRQFUNCTION; +/** + * @defgroup Macrofunctions query + * + * The following are defines used for simplifying calling the mpalQuery variants + */ -/****************************************************************************\ -* Macrofunctions query -\****************************************************************************/ - -/****************************************************************************\ -* -* Function: uint32 mpalQueryVersion(void); -* -* Description: Gets the current version of MPAL -* -* Return: Version number (0x1232 = 1.2.3b) -* -\****************************************************************************/ - +/** + * Gets the current version of MPAL + * + * @returns Version number (0x1232 = 1.2.3b) + */ #define mpalQueryVersion() \ (uint16)mpalQueryDWORD(MPQ_VERSION) - - -/****************************************************************************\ -* -* Function: uint32 mpalQueryGlobalVar(LPSTR lpszVarName); -* -* Description: Gets the numerical value of a global variable -* -* Input: LPSTR lpszVarName Nome della variabile (ASCIIZ) -* -* Return: Valore della variabile -* -* Note: This query was implemented for debugging. The program, -* if well designed, should not need to access variables from -* within the library. -* -\****************************************************************************/ - +/** + * Gets the numerical value of a global variable + * + * @param lpszVarName Nome della variabile (ASCIIZ) + * @returns Global variable value + * @remarks This query was implemented for debugging. The program, + * if well designed, should not need to access variables from + * within the library. + */ #define mpalQueryGlobalVar(lpszVarName) \ mpalQueryDWORD(MPQ_GLOBAL_VAR, (const char *)(lpszVarName)) - -/****************************************************************************\ -* -* Function: HGLOBAL mpalQueryResource(uint32 dwResId); -* -* Description: Provides access to a resource inside the .MPC file -* -* Input: uint32 dwResId ID della risorsa -* -* Return: Handle to a memory area containing the resource, -* ready for use. -* -\****************************************************************************/ - +/** + * Provides access to a resource inside the .MPC file + * + * @param dwResId Resource Id + * @returns Handle to a memory area containing the resource, ready for use. + */ #define mpalQueryResource(dwResId) \ mpalQueryHANDLE(MPQ_RESOURCE, (uint32)(dwResId)) - -/****************************************************************************\ -* -* Function: LPSTR mpalQueryMessage(uint32 nMsg); -* -* Description: Returns a message. -* -* Input: uint32 nMsg Message number -* -* Return: ASCIIZ message -* -* Note: The returned pointer must be freed with GlobalFree() +/** + * Returns a message. + * + * @param nMsg Message number + * @returns ASCIIZ message + * @remarks The returned pointer must be freed via the memory manager * after use. The message will be in ASCIIZ format. -* -\****************************************************************************/ - +*/ #define mpalQueryMessage(nMsg) \ (LPSTR)mpalQueryHANDLE(MPQ_MESSAGE, (uint32)(nMsg)) - -/****************************************************************************\ -* -* Function: HGLOBAL mpalQueryLocationImage(uint32 nLoc); -* -* Description: Provides a image image -* -* Input: uint32 nLoc Locazion number -* -* Return: Returns a picture handle -* -\****************************************************************************/ - +/** + * Provides a location image + * @return Returns a picture handle + */ #define mpalQueryLocationImage(nLoc) \ mpalQueryHANDLE(MPQ_LOCATION_IMAGE, (uint32)(nLoc)) - -/****************************************************************************\ -* -* Function: uint32 mpalQueryLocationSize(uint32 nLoc, uint32 dwCoord); -* -* Description: Request the x or y size of a location in pixels -* -* Input: uint32 nLoc Location number -* uint32 dwCoord MPQ_Xr o MPQ_Y -* -* Return: Size -* -\****************************************************************************/ - +/** + * Request the x or y size of a location in pixels + * + * @param nLoc Location number + * @param dwCoord MPQ_X or MPQ_Y coordinate to retrieve + * @returns Size + */ #define mpalQueryLocationSize(nLoc,dwCoord) \ mpalQueryDWORD(MPQ_LOCATION_SIZE,(uint32)(nLoc),(uint32)(dwCoord)) - -/****************************************************************************\ -* -* Function: uint32 * mpalQueryItemList(uint32 nLoc); -* -* Description: Provides the list of objects in the lease. -* -* Input: uint32 nLoc Location number -* -* Return: List of objects (accessible by Item [0], Item [1], etc.) -* -\****************************************************************************/ -// TODO: Check if the results of this are endian safe +/** + * Provides the list of objects in a location. + * + * @param nLoc Location number + * @returns List of objects (accessible by Item [0], Item [1], etc.) + */ +// TODO: Determine if this is endian safe #define mpalQueryItemList(nLoc) \ (uint32 *)mpalQueryHANDLE(MPQ_ITEM_LIST,(uint32)(nLoc)) - -/****************************************************************************\ -* -* Function: LPBKGANIM mpalQueryItemData(uint32 nItem); -* -* Description: Provides information on an item -*e -* Input: uint32 nItem Item number -* -* Return: structure filled with requested information -* -\****************************************************************************/ - +/** + * Provides information on an item + * + * @param nItem Item number + * @returns Structure filled with requested information + */ #define mpalQueryItemData(nItem) \ (LPITEM)mpalQueryHANDLE(MPQ_ITEM_DATA,(uint32)(nItem)) - -/****************************************************************************\ -* -* Function: uint32 mpalQueryItemPattern(uint32 nItem); -* -* Description: Provides the current pattern of an item -* -* Input: uint32 nItem Item number -* -* Return: Number of animation patterns to be executed. -* -* Note: By default, the pattern of 0 indicates that we should -* do nothing. -* -\****************************************************************************/ - +/** + * Provides the current pattern of an item + * + * @param nItem Item number + * @returns Number of animation patterns to be executed. + * @remarks By default, the pattern of 0 indicates that we should do nothing. + */ #define mpalQueryItemPattern(nItem) \ mpalQueryDWORD(MPQ_ITEM_PATTERN,(uint32)(nItem)) - -/****************************************************************************\ -* -* Function: bool mpalQueryItemIsActive(uint32 nItem); -* -* Description: Returns true if an item is active -* -* Input: uint32 nItem Item number -* -* Return: TRUE if the item is active, FALSE otherwise -* -\****************************************************************************/ - +/** + * Returns true if an item is active + * + * @param nItem Item number + * @returns TRUE if the item is active, FALSE otherwise + */ #define mpalQueryItemIsActive(nItem) \ (bool)mpalQueryDWORD(MPQ_ITEM_IS_ACTIVE,(uint32)(nItem)) -/****************************************************************************\ -* -* Function: void mpalQueryItemName(uint32 nItem, LPSTR lpszName); -* -* Description: Returns the name of an item -* -* Input: uint32 nItem Item number -* LPSTR lpszName Pointer to a buffer of at least 33 bytes -* that will be filled with the name -* -* Note: If the item is not active (ie. if its status or number -* is less than or equal to 0), the string will be empty. -* -\****************************************************************************/ - +/** + * Returns the name of an item + * + * @param nItem Item number + * @param lpszName Pointer to a buffer of at least 33 bytes + * that will be filled with the name + * @remarks If the item is not active (ie. if its status or number + * is less than or equal to 0), the string will be empty. + */ #define mpalQueryItemName(nItem, lpszName) \ mpalQueryHANDLE(MPQ_ITEM_NAME,(uint32)(nItem), (LPSTR)(lpszName)) - -/****************************************************************************\ -* -* Function: LPSTR mpalQueryDialogPeriod(uint32 nDialog, uint32 nPeriod); -* -* Description: Returns a sentence of dialog. -* -* Input: uint32 nDialog Dialog number -* uint32 nPeriod Number of words -* -* Return: A pointer to the string of words, or NULL on failure. -* -* Note: The string must be freed after use by GlobalFree (). -* -* Unlike normal messages, the sentences of dialogue -* are formed by a single string terminated with 0. -* -\****************************************************************************/ - +/** + * Returns a sentence of dialog. + * + * @param nDialog Dialog number + * @param nPeriod Number of words + * @returns A pointer to the string of words, or NULL on failure. + * @remarks The string must be freed after use using the memory manager. + * Unlike normal messages, the sentences of dialogue are formed by a single + * string terminated with 0. + */ #define mpalQueryDialogPeriod(nPeriod) \ (LPSTR)mpalQueryHANDLE(MPQ_DIALOG_PERIOD, (uint32)(nPeriod)) - -/****************************************************************************\ -* -* Function: int mpalQueryDialogWaitForChoice(void); -* -* Description: Wait until the moment in which the need is signaled -* to make a choice by the user. -* -* Return: Number of choice to be made, or -1 if the dialogue is finished. -* -\****************************************************************************/ - +/** + * Wait until the moment in which the need is signaled to make a choice by the user. + * @returns Number of choice to be made, or -1 if the dialogue is finished. + */ #define mpalQueryDialogWaitForChoice(dwRet) \ CORO_INVOKE_2(mpalQueryCORO, MPQ_DIALOG_WAITFORCHOICE, dwRet) -/****************************************************************************\ -* -* Function: uint32 * mpalQueryDialogSelectList(uint32 nChoice); -* -* Description: Requires a list of various options for some choice within -* the current dialog. - -* Input: uint32 nChoice Choice number -* -* Return: A pointer to an array containing the data matched to each option. -* -* Note: The figure 'a uint32 specified in the source to which MPAL -* You can 'assign meaning that the more' suits. -* -* The pointer msut be freed after use by GlobalFree(). -* -\****************************************************************************/ +/** + * Requires a list of various options for some choice within the current dialog. + * + * @param nChoice Choice number + * @returns A pointer to an array containing the data matched to each option. + * @remarks The figure 'a uint32 specified in the source to which MPAL + * You can assign meaning that the more' suits. + * The pointer msut be freed after use using the memory memory. + */ #define mpalQueryDialogSelectList(nChoice) \ (uint32 *)mpalQueryHANDLE(MPQ_DIALOG_SELECTLIST,(uint32)(nChoice)) - -/****************************************************************************\ -* -* Function: bool mpalQueryDialogSelection(uint32 nChoice, uint32 dwData); -* -* Description: Warns the library that the user has selected, in a certain -* choice of the current dialog, corresponding option -* at a certain given. -* -* Input: uint32 nChoice Choice number of the choice that -* was in progress -* uint32 dwData Option that was selected by the user. -* -* Return: TRUE if all OK, FALSE on failure. -* -* Note: After execution of this query, MPAL continue -* Groups according to the execution of the dialogue. And necessary so the game -* remains on hold again for another Chosen by mpalQueryDialogWaitForChoice (). -* -\****************************************************************************/ - +/** + * Warns the library that the user has selected, in a certain choice of the current dialog, + * corresponding option at a certain given. + * + * @param nChoice Choice number of the choice that was in progress + * @param dwData Option that was selected by the user. + * @returns TRUE if all OK, FALSE on failure. + * @remarks After execution of this query, MPAL continue + * Groups according to the execution of the dialogue. And necessary so the game + * remains on hold again for another chosen by mpalQueryDialogWaitForChoice (). + */ #define mpalQueryDialogSelection(nChoice,dwData) \ (bool)mpalQueryDWORD(MPQ_DIALOG_SELECTION,(uint32)(nChoice),(uint32)(dwData)) @@ -526,245 +399,169 @@ typedef LPITEMIRQFUNCTION* LPLPITEMIRQFUNCTION; mpalQueryDWORD(MPQ_DIALOG_SELECTION,(uint32)(nChoice),(uint32)(dwData)) -/****************************************************************************\ -* -* Function: HANDLE mpalQueryDoAction(uint32 nAction, uint32 nItem, -* uint32 dwParam); -* -* Description: Warns the library an action was performed on a Object. -* The library will call 'custom functions, if necessary. -* -* Input: uint32 nAction Action number -* uint32 nItem Item number -* uint32 dwParam Action parameter -* -* Return: Handle to the thread that is performing the action, or -* CORO_INVALID_PID_VALUE if the action is not 'defined for -* the item, or the item and 'off. -* -* Note: The parameter is used primarily to implement actions -* as "U.S." involving two objects together. The action will be executed only -* if the item is active, ie if its status is a positive number greater than 0. -* -\****************************************************************************/ - +/** + * Warns the library an action was performed on a Object. + * The library will call custom functions, if necessary. + * + * @param nAction Action number + * @param nItem Item number + * @param dwParam Action parameter + * @returns Handle to the thread that is performing the action, or CORO_INVALID_PID_VALUE + * if the action is not defined for the item, or the item is inactive. + * @remarks The parameter is used primarily to implement actions + * as "U.S." involving two objects together. The action will be executed only + * if the item is active, ie if its status is a positive number greater than 0. + */ #define mpalQueryDoAction(nAction, nItem, dwParam) \ mpalQueryDWORD(MPQ_DO_ACTION, (uint32)(nAction), (uint32)(nItem), (uint32)(dwParam)) - -/****************************************************************************\ -* -* Function: HANDLE mpalQueryDoDialog(uint32 nDialog, uint32 nGroup); -* -* Description: Warns the library a dialogue was required. -* -* Input: uint32 nDialog Dialog number -* uint32 nGroup Group number to use -* -* Return: Handle to the thread that is running the box, or -* CORO_INVALID_PID_VALUE if the dialogue does not exist. -* -\****************************************************************************/ - +/** + * Warns the library a dialogue was required. + * + * @param nDialog Dialog number + * @param nGroup Group number to use + * @returns Handle to the thread that is running the box, or + * CORO_INVALID_PID_VALUE if the dialogue does not exist. + */ #define mpalQueryDoDialog(nDialog,nGroup) \ mpalQueryDWORD(MPQ_DO_DIALOG, (uint32)(nDialog),(uint32)(nGroup)) -/****************************************************************************\ -* Functions exported to the main game -\****************************************************************************/ - +/** + * @defgroup Functions exported to the main game + */ -/****************************************************************************\ -* -* Function: bool mpalInit(LPSTR lpszMpcFileName, LPSTR lpszMprFileName, -* LPLPCUSTOMFUNCTION lplpcfArray); -* -* Description: Initializes the MPAL library, and opens an .MPC file, which -* will be 'used for all queries -* -* Input: LPSTR lpszMpcFileName Name of the .MPC file, including extension -* LPSTR lpszMprFileName Name of the .MPR file, including extension -* LPLPCUSTOMFUNCTION Array of pointers to custom functions -* -* Return: TRUE if all OK, FALSE on failure -* -\****************************************************************************/ +/** + * Initializes the MPAL library, and opens an .MPC file, which will be 'used for all queries + * @param lpszMpcFileName Name of the .MPC file, including extension + * @param lpszMprFileName Name of the .MPR file, including extension + * @param lplpcfArray Array of pointers to custom functions + * @returns TRUE if all OK, FALSE on failure + */ bool mpalInit(const char *lpszFileName, const char *lpszMprFileName, LPLPCUSTOMFUNCTION lplpcfArray, Common::String *lpcfStrings); - -/****************************************************************************\ -* -* Function: uint32 mpalQuery(uint16 wQueryType, ...); -* -* Description: This is the general function to communicate with the library, -* To request information about what is in the .MPC file -* -* Input: uint16 wQueryType Type of query. The list is in -* the QueryTypes enum. -* -* Return: 4 bytes depending on the type of query -* -* Note: I _strongly_ recommended to use macros defined above to use -* the query, since it helps avoid any unpleasant bugs due to -* forgeting parameters. -* -\****************************************************************************/ - -typedef void *HANDLE; - +/** + * This is a general function to communicate with the library, to request information + * about what is in the .MPC file + * + * @param wQueryType Type of query. The list is in the QueryTypes enum. + * @returns 4 bytes depending on the type of query + * @remarks This is the specialised version of the original single mpalQuery + * method that returns numeric results. + */ uint32 mpalQueryDWORD(uint16 wQueryType, ...); +/** + * This is a general function to communicate with the library, to request information + * about what is in the .MPC file + * + * @param wQueryType Type of query. The list is in the QueryTypes enum. + * @returns 4 bytes depending on the type of query + * @remarks This is the specialised version of the original single mpalQuery + * method that returns a pointer or handle. + */ HANDLE mpalQueryHANDLE(uint16 wQueryType, ...); +/** + * This is a general function to communicate with the library, to request information + * about what is in the .MPC file + * + * @param wQueryType Type of query. The list is in the QueryTypes enum. + * @returns 4 bytes depending on the type of query + * @remarks This is the specialised version of the original single mpalQuery + * method that needs to run within a co-routine context. + */ void mpalQueryCORO(CORO_PARAM, uint16 wQueryType, uint32 *dwRet, ...); -/****************************************************************************\ -* -* Function: bool mpalExecuteScript(int nScript); -* -* Description: Execute a script. The script runs on multitasking by a thread. -* -* Input: int nScript Script number to run -* -* Return: TRUE if the script 'was launched, FALSE on failure -* -\****************************************************************************/ +/** + * Execute a script. The script runs on multitasking by a thread. + * + * @param nScript Script number to run + * @returns TRUE if the script 'was launched, FALSE on failure + */ bool mpalExecuteScript(int nScript); - -/****************************************************************************\ -* -* Function: uint32 mpalGetError(void); -* -* Description: Returns the current MPAL error code -* -* Return: Error code -* -\****************************************************************************/ - +/** + * Returns the current MPAL error code + * + * @returns Error code + */ uint32 mpalGetError(void); - -/****************************************************************************\ -* -* Function: void mpalInstallItemIrq(LPITEMIRQFUNCTION lpiifCustom); -* -* Description: Install a custom routine That will be called by MPAL -* every time the pattern of an item has-been changed. -* -* Input: LPITEMIRQFUNCTION lpiifCustom Custom function to install -* -\****************************************************************************/ - +/** + * Install a custom routine That will be called by MPAL every time the pattern + * of an item has been changed. + * + * @param lpiifCustom Custom function to install + */ void mpalInstallItemIrq(LPITEMIRQFUNCTION lpiifCustom); -/****************************************************************************\ -* -* Function: bool mpalStartIdlePoll(int nLoc); -* -* Description: Process the idle actions of the items on one location. -* -* Input: int nLoc Number of the location whose items -* must be processed for idle actions. -* -* Return: TRUE if all OK, and FALSE if it exceeded the maximum limit. -* -* Note: The maximum number of locations that can be polled -* simultaneously is defined defined by MAXPOLLINGFUNCIONS -* -\****************************************************************************/ - +/** + * Process the idle actions of the items on one location. + * + * @param nLoc Number of the location whose items must be processed + * for idle actions. + * @returns TRUE if all OK, and FALSE if it exceeded the maximum limit. + * @remarks The maximum number of locations that can be polled + * simultaneously is defined defined by MAXPOLLINGFUNCIONS + */ bool mpalStartIdlePoll(int nLoc); -/****************************************************************************\ -* -* Function: bool mpalEndIdlePoll(int nLoc); -* -* Description: Stop processing the idle actions of the items on one location. -* -* Input: int nLoc Number of the location -* -* Return: TRUE if all OK, FALSE if the specified location was not -* in the process of polling -* -\****************************************************************************/ - +/** + * Stop processing the idle actions of the items on one location. + * + * @param nLo Number of the location + * @returns TRUE if all OK, FALSE if the specified location was not + * in the process of polling + */ void mpalEndIdlePoll(CORO_PARAM, int nLoc, bool *result); -/****************************************************************************\ -* -* Function: int mpalLoadState(LPBYTE buf); -* -* Description: Load a save state from a buffer. -* -* Input: LPBYTE buf Buffer where to store the state -* -* Return: Length of the state in bytes -* -\****************************************************************************/ - +/** + * Load a save state from a buffer. + * + * @param buf Buffer where to store the state + * @returns Length of the state buffer in bytes + */ int mpalLoadState(byte *buf); - -/****************************************************************************\ -* -* Function: void mpalSaveState(LPBYTE buf); -* -* Description: Store the save state into a buffer. The buffer must be -* length at least the size specified with mpalGetSaveStateSize -* -* Input: LPBYTE buf Buffer where to store the state -* -\****************************************************************************/ - +/** + * Store the save state into a buffer. The buffer must be + * length at least the size specified with mpalGetSaveStateSize + * + * @param buf Buffer where to store the state + */ void mpalSaveState(byte *buf); - -/****************************************************************************\ -* -* Function: int mpalGetSaveStateSize(void); -* -* Description: Acquire the length of a save state -* -* Return: Length in bytes -* -\****************************************************************************/ - +/** + * Retrieve the length of a save state + * + * @returns Length in bytes + */ int mpalGetSaveStateSize(void); -/****************************************************************************\ -* -* Function: void LockVar(void); -* -* Description: Locka le variabili per accederci -* -\****************************************************************************/ - -extern void LockVar(void); +/** + * Locks the variables for access + */ +void LockVar(void); -/****************************************************************************\ -* -* Function: void UnlockVar(void); -* -* Description: Unlocka le variabili dopo l'uso -* -\****************************************************************************/ -extern void UnlockVar(void); +/** + * Unlocks variables after use + */ +void UnlockVar(void); } // end of namespace MPAL -- cgit v1.2.3