Custom Action Example

There is often a need to look information up in a database. The following example will show how to set up a Custom Action dynamic link library. The call flow which the CA DLL will support is shown below.

This example will focus on the PinNumber Module support. The other modules and their CA functions may be mentioned, but will not be detailed here. The first issue will be our User Data. This will be defined in a header of the Custom Action DLL project.

C++ Code

  1. struct AccountInfo
  2. {
  3. LONG AccountNo;
  4. LONG PinNo;
  5. LONG StateCode;
  6. LONG CityCode;
  7. CHAR SocialSec[20];
  8. LONG Age;
  9. };

The LV_Call_Start function is a recommended function that will be called if found in the CA DLL. This function will receive notification that a call is starting. This is a very good place to create and store the User Data.

C++ Code

  1. __declspec(dllexport) BOOL WINAPI LV_Call_Start(LONG nMsg, HANDLE hCA)
  2. {
  3. AccountInfo* pAI = new AccountInfo;
  4. memset(pAI, 0, sizeof(AccountInfo));
  6. if(!LVCA_SetUserData(hCA, pAI))
  7. {
  8. /*
  9.         error An Error is anything within the system
  10.         itself that creates a glitch in the Speech
  11.         Driven Information System, such as a missing
  12.         Vox or a Goto that doesn't go anywhere.handing;
  13.         */
  14. }
  15.  
  16. return true;
  17. }

When the call ends the LV_Call_End function will be called. This is the logical place to clean up the user data.

C++ Code

  1. __declspec(dllexport) BOOL WINAPI LV_Call_End(LONG nMsg, HANDLE hCA)
  2. {
  3. AccountInfo* pAI;
  5. if(!LVCA_GetUserData(hCA, (LPVOID *) &pAI))
  6. {
  7. //error handling;
  8. }
  10. delete pAI;
  11. LVCA_SetUserData(hCA, NULL);
  13. return true;
  14. }

A definition file should be created for the project. This text file specifies the exported functions. Here is an example of what the .def file would look like:

LIBRARY "CA_Test"
EXPORTS
LV_Call_Start
LV_Call_End

Here is how the PinNumber module will look in the Designer.

Notice there is no audio and the grammar has no concepts in it. The Custom DLL property has a Custom Action DLL filename. The function that the module is going to look for is PinModule. This function will need to be defined in the CA DLL.

C++ Code

  1. __declspec(dllexport) BOOL WINAPI PinModule(LONG nEvent, HANDLE hCA)
  2. {
  3. switch(nEvent)
  4. {
  5. case CAMSG_POLL:
  6. return TRUE;
  8. case CAMSG_ENTERMODULE:
  10. LVCA_AddMainLibraryAudio(hCA, "EnterPin");
  11. LVCA_AddStandardGrammar(hCA, CA_GRAMMAR_DIGITS);
  12. break;
  13. case CAMSG_REC_BEFORE_CONFIRM:
  14. CheckPin(hCA);
  15. break;
  16. }
  18. return TRUE;
  19. }

In the above example, notice that the CAMSG_ENTERMODULE has two functions being called. The LVCA_AddMainLibraryAudio function is adding audio, defined in the Designer's Audio Manager. LVCA_AddStandardGrammar is adding the built-in digits grammar. The event CAMSG_REC_BEFORE_CONFIRM is calling CheckPin. The function needs to extract the raw concept and save it as a pin number in the user data. Since it is possible for the concept to be a Designer defined grammar, the LVCA_IsCustom function checks the response.

C++ Code

  1. VOID CheckPin(HANDLE hCA)
  2. {
  3. LONG nCount;
  4. LONG nSize = 1024;
  5. LONG nConf = 0;
  7. if (!LVCA_GetRawConceptCount(hCA, &nCount))
  8. {
  9. INT nErr = LVCA_GetLastCallError(hCA, m_szErrStr, &nSize);
  11. if(!nErr)
  12. nErr = LVCA_GetLastSystemError(m_szErrStr, &nSize);
  14. ReportError(nErr);
  16. return;
  17. }
  19. BOOL bIsCustom;
  20. TCHAR szConcept[1024];
  21.  
  22. //for brevity just getting the first concept;
  23.  
  24. if(!LVCA_GetRawConcept(hCA, 0, szConcept, &nSize, &nConf))
  25. {
  26. //error handling
  27. }
  29. if(!LVCA_IsCustomConcept(hCA, &bIsCustom, szConcept))
  30. {
  31. //error handling
  32. }
  34. if(!bIsCustom) //this protects a global concept from being intercepted
  35.  
  36. return;
  38. AccountInfo* pAI;
  40. if(!LVCA_GetUserInfo(hCA, (LPVOID *) &pAI)
  41. {
  42. //error handling
  43. }
  45. pAI->PinNo = atol(szConcept);
  47. //this function would perform a database lookup on the account and pin.
  48. if(!Login(pAI))
  49. {
  50. LVCA_AddOneTimeLibraryAudio(hCA, "Bad Pin Number or Account");
  51. LVCA_SetGoto(hCA, "AccountNo");
  52. }
  53. else
  54. {
  55. LVCA_SetGoto(hCA, "User Settings Needed");
  56. }
  57. }

Finally, the PinModule function needs to be added to the .def file.

LIBRARY "CA_Test"
EXPORTS
LV_Call_Start
LV_Call_End
PinModule

© 2012 LumenVox LLC. All rights reserved.