home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / VISUAL_B / FERRAMEN / X_TASK / XTASK.TXT < prev   
Encoding:
Text File  |  1992-11-16  |  4.4 KB  |  94 lines
  1. Name:      xTask.dll
  2. Purpose:   Monitoring termination of other tasks;
  3.            Mapping between hTask and hInstance.
  4. Version:   1.0
  5. Date:      15 Nov 92
  6. Requires:  Windows 3.1
  7. Author:    Pieter Stam (CompuServe 100065,603),  Pontis Consulting (U.K.)
  8. Ownership: Public.  Free usage & redistribution.
  9.            *** USE THIS LIBRARY AT YOUR OWN RISK *** 
  10.            Be sure to test thoroughly in your environment. 
  11.            No warrantees extended, no support promised.
  12.            Please report any problems back to the author.
  13.  
  14.  
  15. Introduction
  16. ------------
  17.  
  18. This DLL will allow you to detect the termination of any EXE. 
  19. You pass a window handle of the calling application along with 
  20. the task handle of another running application, and a number of 
  21. your own choice.  The function returns immediately.  When the 
  22. application exits, the window specified receives a WM_KEYDOWN 
  23. message with as argument the number of your choice plus the 
  24. exit code of the terminated application (e.g. of a DOS 
  25. application in a DOS box).  
  26. One application can monitor several applications.  
  27. One application can be monitored by several applications.
  28.  
  29. In VB, you could have started an application with 'Shell'.  
  30. 'Shell' returns an instance handle, that you can map to a task 
  31. handle with this library.  You start monitoring by calling this 
  32. library, passing the task handle, a Form's hWnd, and a number of 
  33. your choice.  When the monitored application exits, the 
  34. Form_KeyDown event happens for the form of which the hWnd was 
  35. passed.  The argument 'KeyCode' equals your number plus exit 
  36. code.  Your code in the Form_KeyDown subroutine of your 
  37. application can then do its business.
  38.  
  39. NOTE:  This ONLY will work with Windows 3.1 and later.  
  40. Various functions (i.a. NotifyRegister) of ToolHelp.DLL 
  41. of 3.1 are used.
  42.  
  43.  
  44. Interface definition
  45. --------------------
  46.  
  47. * Visual Basic:
  48.  
  49. Declare Function SetTaskExitWatch Lib "xTask.dll" (ByVal hTaskToWatch As Integer, ByVal hWndRecipient As Integer, ByVal kCode As Integer) As Integer
  50. Declare Function CancelTaskExitWatches Lib "xTask.dll" (ByVal hWndRecipient As Integer) As Integer
  51. Declare Function hTaskFromhInstance Lib "xTask.dll" (ByVal hInstance As Integer) As Integer
  52. Declare Function hInstanceFromhTask Lib "xTask.dll" (ByVal hTask As Integer) As Integer
  53.  
  54. * C:
  55.  
  56. #include <Windows.h>
  57. BOOL      WINAPI SetTaskExitWatch( HTASK ToWatch, HWND Recipient, WPARAM kCode );
  58. UINT      WINAPI CancelTaskExitWatches( HWND );
  59. HTASK     WINAPI hTaskFromhInstance( HINSTANCE );
  60. HINSTANCE WINAPI hInstanceFromhTask( HTASK );
  61.  
  62. * Semantics:
  63.  
  64. SetTaskExitWatch returns 0 on failure, e.g. when the task does not exist,
  65. or when internal resources are exhausted (there can be 16 'TaskExitWatches',
  66. but Windows 3.1 seems to support only 12 RegisterNotify callback settings).
  67. Upon success it returns hex FFFF (-1, as traditional in VB for booleans).
  68. When the monitored task exits, the recipient window receives a WM_KEYDOWN event
  69. with LPARAM 0 and WPARAM equal to kCode + exit code of terminating app (0-255).
  70. In VB this means a KeyDown event for the Form whose hWnd was specified;
  71. the KeyCode argument is kCode of SetExitTaskWatch plus exit code.
  72. It seems safest & easiest to use kCode values 256, 512, ...
  73. Warning:
  74. If the receiving VB application happens to display a MsgBox when a monitored
  75. application exits, the Form_KeyDown event does not happen;
  76. this is an officially recognized VB "feature".
  77. (Things work fine when another form is being shown, modal or modeless.)
  78.  
  79. CancelTaskExitWatches is a cleanup routine that one 'should' use before
  80. destroying the window, if there may still be monitored applications alive.
  81. In VB one could call it in Form_Unload.  Failure to do so may lead to
  82. misinterpreted messages to windows created later with a recycled handle.
  83. The function returns the number of TaskExitWatches that have been cancelled.
  84.  
  85. hTaskFromhInstance returns the Task handle belonging to the argument Instance
  86. handle.  (Note that VB's Shell, like Window's WinExec, returns an Instance
  87. handle.)  If the argument is 0, it returns the Task handle of the caller.
  88. On errors (typically: hInstance not found in system) it returns 0.
  89.  
  90. hInstanceFromhTask returns the Instance handle belonging to the argument Task
  91. handle.  If the argument is 0, it returns the Instance handle of the caller.
  92. On errors (typically: hTask not found in system) it returns 0.
  93.  
  94.