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