home *** CD-ROM | disk | FTP | other *** search
/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / include / eman.idl < prev    next >
Encoding:
Text File  |  1996-02-21  |  6.7 KB  |  191 lines
  1. //
  2. //   COMPONENT_NAME: somu
  3. //
  4. //   ORIGINS: 27
  5. //
  6. //
  7. //   10H9767, 10H9769  (C) COPYRIGHT International Business Machines Corp. 1992,1994
  8. //   All Rights Reserved
  9. //   Licensed Materials - Property of IBM
  10. //   US Government Users Restricted Rights - Use, duplication or
  11. //   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
  12. //
  13.  
  14.  
  15. #ifndef eman_idl
  16. #define eman_idl
  17.  
  18. #include <somobj.idl>
  19. #include <snglicls.idl>
  20.  
  21. interface SOMEEvent;
  22. interface SOMEClientEvent;
  23. interface SOMEEMRegisterData;
  24.  
  25. typedef somToken EMRegProc;
  26. typedef somToken EMMethodProc;
  27. typedef somToken EMMethodProcEv;
  28.  
  29. /*
  30.  * Signatures of callback routines are FIXED. A callback MUST HAVE one of the
  31.  * following signatures.
  32.  *
  33.  * typedef for void EMRegProc(SOMEEvent *, void *);
  34.  * (Procedure registration callback interface. Uses "system" linkage on OS/2).
  35.  *
  36.  * typedef for void SOMLINK EMMethodProc(SOMObject *, SOMEEvent *, void *);
  37.  * (Method registration callback interface. Uses "system" linkage on OS/2.)
  38.  *
  39.  * typedef void SOMLINK EMMethodProcEv(SOMObject *, Environment *, SOMEEvent *, void *);
  40.  * (Method registration callback interface(with Ev). Uses "system" linkage on OS/2.)
  41.  */
  42.  
  43.  
  44. interface SOMEEMan : SOMObject
  45.  
  46. // The Event Manager class (EMan for short) is used to handle several input
  47. // events. The main purpose of this class is to provide a service that can do
  48. // a blocked (or timed) wait on several event sources concurrently.  Typically,
  49. // in a main program,  one registers an interest in an event type with EMan and 
  50. // specifies a callback (a procedure or a method) to be invoked when the event
  51. // of interest occurs. After all the necessary registrations are done, the main
  52. // program is ended by a call to process events in EMan. This call is non-returning.
  53. // Eman then waits on multiple registered sources of events. The application is then
  54. // completely event driven. I.E., it does something only when an event occurs.
  55. // The control returns to EMan after processing each event. Further registrations
  56. // can be done inside of callback routines. So also unregistrations.
  57. //
  58. // AIX Specifics: 
  59. // On AIX this event manager supports Timer, Sink (any file, pipe,
  60. // socket and Message Queue), Client and WorkProc events.
  61. //
  62. // OS/2 Specifics:
  63. // On OS/2 this event manager supports Timer, Sink(sockets only). Client and
  64. // WorkProc events.
  65. // To cope with multi-threaded applications on OS/2, the event manager
  66. // methods are mutually exclusive (i.e., at any time only one thread can be
  67. // executing inside of EMan).
  68. // If an application thread needs to stop EMan from running (i.e., achieve
  69. // mutual exclusion with EMan), it can use the two methods someGetEmanSem 
  70. // and someReleaseEManSem to acquire and release EMan semaphore(s).
  71. // On AIX, at present, since AIX does not support threads calling these two methods
  72. // has no effect.
  73.  
  74. {
  75.  
  76.     void someGetEManSem();
  77.  
  78.     // Gets a semaphore to achieve mutual exclusion with EMan's activity.
  79.     // Callers should not hold this semaphore for too long since it essentially
  80.     // stops EMan activity for that duration.
  81.  
  82.     void someReleaseEManSem();
  83.     // Release the semaphore obtained by someGetEManSem.
  84.  
  85.   void someChangeRegData(in long registrationId,
  86.                           in SOMEEMRegisterData registerData);
  87.  
  88.   // Change the registration data associated with the specified id.
  89.   // This id must have been returned by EMan in a previous Register call.
  90.  
  91.   void someProcessEvent(in unsigned long mask);
  92.  
  93.   // Process one event. This call is non-blocking. If there are no events to
  94.   // process it returns immediately. The mask specifies what events to process.
  95.   // The mask is formed by ORing the bit constants specified in eventmsk.h
  96.   // For example, to processs Timer and Sink events only one would specify
  97.   // the mask as:  EMProcessTimerEvent | EMProcessSinkEvent
  98.  
  99. #ifdef _WIN16
  100.   void someProcessEventInterval(in unsigned long mask, 
  101.            in unsigned long interval, in unsigned long inst);
  102.  
  103.   // Process one event. This call is non-blocking. If there are no events to
  104.   // process it returns immediately. The mask specifies what events to process.
  105.   // The mask is formed by ORing the bit constants specified in eventmsk.h
  106.   // For example, to processs Timer and Sink events only one would specify
  107.   // the mask as:  EMProcessTimerEvent | EMProcessSinkEvent
  108. #endif   
  109.  
  110.   void someProcessEvents();
  111.  
  112.   // Process infinite events. Does not return. Loops forever waiting for events
  113.   // and dispatching events. The only way this can be broken is by calling 
  114.   // someShutdown in a callback.
  115.  
  116.   void someQueueEvent(in SOMEClientEvent event);
  117.   /* Used to be: void someQueueEvent(inout SOMEClientEvent event);*/
  118.  
  119.   // Enqueue the specified client event
  120.  
  121.   long someRegister(in SOMEEMRegisterData registerData,
  122.                     in SOMObject targetObject,
  123.                     in string targetMethod,
  124.                     in void *targetData);
  125.  
  126.   // Register the object/method pair with EMan given the specified 'registerData'.
  127.  
  128.   long someRegisterEv(in SOMEEMRegisterData registerData,
  129.                     in SOMObject targetObject,
  130.                     inout Environment callbackEv,
  131.                     in string targetMethod,
  132.                     in void *targetData);
  133.  
  134.   // Register the object/method pair together with the callback Environment parameter
  135.   // with EMan given the specified 'registerData'.
  136.  
  137.   long someRegisterProc(in SOMEEMRegisterData registerData,
  138.                         in EMRegProc *targetProcedure,
  139.                         in void *targetData);
  140.  
  141.   // Register the procedure with EMan given the specified 'registerData'.
  142.  
  143.   void someShutdown();
  144.  
  145.   // Shutdown EMan event loop. (i.e., makes the someProcessEvents return!)
  146.  
  147.   void someUnRegister(in long registrationId);
  148.  
  149.   // Unregister the data associated with the specified 'registrationId' within EMan
  150.  
  151.  
  152. #ifdef __SOMIDL__
  153.   implementation {
  154.  
  155.     releaseorder: someGetEManSem, someReleaseEManSem,
  156.                   someChangeRegData,
  157.                   someProcessEvent,someProcessEvents,
  158.                   someQueueEvent,
  159.                   someRegister,someRegisterEv, someRegisterProc,
  160.                   someShutdown,someUnRegister
  161. #ifdef _WIN16
  162.           ,
  163.           someProcessEventInterval
  164. #endif
  165.                   ;
  166.  
  167.     majorversion = 2;
  168.     minorversion = 1;
  169.     filestem = eman;
  170.     metaclass = SOMMSingleInstance;
  171.     callstyle = idl;
  172.  
  173.     passthru C_h_after =   "#include <emtypes.h>";
  174.     passthru C_xh_after =   "extern \"C\" {"
  175. "#include <emtypes.h>"
  176. "}";
  177.     passthru C_hh_after =   "extern \"C\" {"
  178. "#include <emtypes.h>"
  179. "}";
  180.  
  181.  
  182.     somInit: override;
  183.     somUninit: override;
  184.  
  185.   };
  186. #endif /* __SOMIDL__ */
  187. };
  188.  
  189. #endif  /* eman_idl */
  190.  
  191.