home *** CD-ROM | disk | FTP | other *** search
/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / include / somcm.idl < prev    next >
Encoding:
Text File  |  1996-02-21  |  11.0 KB  |  244 lines
  1. //
  2. //   COMPONENT_NAME: somk
  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. //   Change History
  14. //   95/11/08  MC    -This is the SOM2.5 version of the class manager
  15. //                    being used for the SOM2.1 port to NT.
  16.  
  17. //  SOMClassMgr: System Object Model class manager
  18.  
  19. #ifndef somcm_idl
  20. #define somcm_idl
  21.  
  22. #include <somobj.idl>
  23.  
  24. interface Repository;
  25.  
  26. interface SOMClassMgr : SOMObject
  27. {
  28.   // [Basic Functions Group]
  29.  
  30.   typedef SOMClass *SOMClassArray;
  31.   // Used for SOM 1.0 binary compatibility
  32.  
  33.  
  34.   SOMClass somLoadClassFile(in somId classId,
  35.                             in long majorVersion,
  36.                             in long minorVersion,
  37.                             in string file);
  38.   // Loads the class' code and initializes the class object.
  39.  
  40.   string somLocateClassFile(in somId classId,
  41.                             in long majorVersion,
  42.                             in long minorVersion);
  43.   // Real implementation supplied by subclasses.  Default implementation
  44.   // will lookup the class name in the Interface Repository (if one is
  45.   // available) to determine the implementation file name (ie, DLL name).
  46.   // If this information is not available, the class name itself is
  47.   // returned as the file name.   Subclasses may use version number
  48.   // info to assist in deriving the file name.
  49.  
  50.   void somRegisterClass(in SOMClass classObj);
  51.   // Lets the class manager know that the specified class is installed
  52.   // and tells it where the class object is.
  53.  
  54.   void somRegisterClassLibrary (in string libraryName,
  55.                                 in somMethodPtr libraryInitRtn);
  56.   // Informs the class manager that a class library has been loaded.
  57.   // "libraryName" is the name associated with the file containing the
  58.   // implementation(s) of the class(es) in the class library.
  59.   // "libraryInitRtn" is the entry point of a SOMInitModule function
  60.   // that can be used to initialize the class library.  For platforms
  61.   // that have the capability to automatically invoke a library
  62.   // initialization function whenever a library is loaded, a call
  63.   // to this method should occur within the library's automatic init
  64.   // function.
  65.  
  66.   void somUnregisterClassLibrary (in string libraryName);
  67.   // Informs the class manager that a class library has been unloaded.
  68.   // "libraryName" is the name associated with the file containing the
  69.   // implementation(s) of the class(es) in the class library.
  70.   // For platforms that have the capability to automatically invoke a
  71.   // library termination function whenever a library is unloaded, a call
  72.   // to this method should occur within the library's automatic
  73.   // termination function.
  74.  
  75.   long somUnloadClassFile(in SOMClass classObj);
  76.   // Releases the class' code and unregisters all classes in the
  77.   // same affinity group (see somGetRelatedClasses below).
  78.  
  79.   long somUnregisterClass(in SOMClass classObj);
  80.   // Free the class object and removes the class from the SOM registry.
  81.   // If the class caused dynamic loading to occur, it is also unloaded
  82.   // (causing its entire affinity group to be unregistered as well).
  83.  
  84.   void somBeginPersistentClasses();
  85.   // Starts a bracket for the current thread wherein all classes
  86.   // that are registered are marked as permanant and cannot be
  87.   // unregistered or unloaded.  Persistent classes brackets may be
  88.   // nested.
  89.  
  90.   void somEndPersistentClasses();
  91.   // Ends a persistent classes bracket for the current thread.
  92.  
  93.   boolean somJoinAffinityGroup(in SOMClass newClass, in SOMClass affClass);
  94.   // If <affClass> is a member of an affinity group, and <newClass> is not a
  95.   // member of any affinity group, this method adds <newClass> to the
  96.   // same affinity group as <affClass>.  If the method succeeds it returns
  97.   // TRUE, otherwise it returns FALSE.  Adding a class to an affinity group
  98.   // effectively equates its lifetime with that of the other members of
  99.   // the affinity group.
  100.  
  101.  
  102.   // [Access Group]
  103.  
  104.   string somGetInitFunction();
  105.   // The name of the initialization function in the class' code file.
  106.   // Default implementation returns (*SOMClassInitFuncName)().
  107.  
  108.   attribute Repository somInterfaceRepository;
  109.   // The Repository object that provides access to the Interface Repository,
  110.   // If no Interface Repository has yet been assigned to this attribute,
  111.   // and the SOMClassMgr is unable to load and instantiate it, the attribute
  112.   // will have the value NULL.  When finished using the Repository object
  113.   // you should release your reference using the somDestruct method with
  114.   // a non-zero <doFree> parameter.
  115.  
  116.   readonly attribute sequence<SOMClass> somRegisteredClasses;
  117.   // A list of all classes currently registered in this process.
  118.  
  119.   SOMClassArray somGetRelatedClasses(in SOMClass classObj);
  120.   // Returns an array of class objects that were all registered during
  121.   // the dynamic loading of a class.    These classes are considered to
  122.   // define an affinity group.  Any class is a member of at most one
  123.   // affinity group.    The affinity group returned by this call is the
  124.   // one containing the class identified by classObj.  The first element
  125.   // in the array is the class that caused the group to be loaded, or the
  126.   // special value -1 which means that the SOMClassMgr is currently in the
  127.   // process of unregistering and deleting the affinity group (only
  128.   // SOMClassMgr subclasses would ever see this value).
  129.   // The remainder of the array (elements one thru n) consists of
  130.   // pointers to class objects ordered in reverse chronological sequence
  131.   // to that in which they were originally registered.  This list includes
  132.   // the given argument, classObj, as one of its elements, as well as the
  133.   // class, if any, returned as element[0] above.  The array is terminated
  134.   // by a NULL pointer as the last element.  Use SOMFree to release the
  135.   // array when it is no longer needed.  If the supplied class was not
  136.   // dynamically loaded, it is not a member of any affinity
  137.   // group and NULL is returned.
  138.  
  139.   // [Dynamic Group]
  140.  
  141.   SOMClass somClassFromId(in somId classId);
  142.   // Finds the class object, given its Id, if it already exists.
  143.   // Does not load the class.  Returns NULL if the class object does
  144.   // not yet exist.
  145.  
  146.   SOMClass somFindClass(in somId classId,
  147.                         in long majorVersion,
  148.                         in long minorVersion);
  149.   // Returns the class object for the specified class.  This may result
  150.   // in dynamic loading.  Uses somLocateClassFile to obtain the name of
  151.   // the file where the class' code resides, then uses somFindClsInFile.
  152.  
  153.   SOMClass somFindClsInFile(in somId classId,
  154.                             in long majorVersion,
  155.                             in long minorVersion,
  156.                             in string file);
  157.   // Returns the class object for the specified class.  This may result
  158.   // in dynamic loading.  If the class already exists <file> is ignored,
  159.   // otherwise it is used to locate and dynamically load the class.
  160.   // Values of 0 for major and minor version numbers bypass version checking.
  161.  
  162.   void somMergeInto(in SOMObject targetObj);
  163.   // Merges the SOMClassMgr registry information from the receiver to
  164.   // <targetObj>.  <targetObj> is required to be an instance of SOMClassMgr
  165.   // or one of its subclasses.  At the completion of this operation,
  166.   // the <targetObj> should be able to function as a replacement for the
  167.   // receiver.  At the end of the operation the receiver object (which is
  168.   // then in a newly uninitialized state) is freed.  Subclasses that
  169.   // override this method should similarly transfer their sections of
  170.   // the object and pass this method to their parent as the final step.
  171.   // If the receiving object is the distinguished instance pointed to
  172.   // from the global variable SOMClassMgrObject, SOMCLassMgrObject is
  173.   // then reassigned to point to <targetObj>.
  174.  
  175.   long somSubstituteClass(in string origClassName,
  176.                           in string newClassName);
  177.   // This method causes the somFindClass, somFindClsInFile, and
  178.   // somClassFromId methods to return the class named newClassName
  179.   // whenever they would have normally returned the class named
  180.   // origClassName.  This effectively results in class <newClassName>
  181.   // replacing or substituting itself for class <origClassName>.
  182.   // Some restrictions are enforced to insure that this works well.
  183.   // Both class <origClassName> and class <newClassName> must
  184.   // have been already registered before issuing this method, and newClass
  185.   // must be an immediate child of origClass.  In addition (although not
  186.   // enforceable), no instances should exist of either class at the time
  187.   // this method is invoked.    A return value of zero indicates success;
  188.   // a non-zero value indicates an error was detected.
  189.  
  190. #ifdef __SOMIDL__
  191.   implementation {
  192.     releaseorder: somFindClsInFile,somFindClass,
  193.                   somClassFromId,somRegisterClass,
  194.                   somUnregisterClass,somLocateClassFile,somLoadClassFile,
  195.                   somUnloadClassFile,somGetInitFunction,somMergeInto,
  196.                   somGetRelatedClasses,somSubstituteClass,
  197.                   _get_somInterfaceRepository, _set_somInterfaceRepository,
  198.                   _get_somRegisteredClasses,
  199.                   somBeginPersistentClasses, somEndPersistentClasses,
  200.                   somcmPrivate1,
  201.                   somcmPrivate2,
  202.                   somRegisterClassLibrary,
  203.                   somJoinAffinityGroup,
  204.                   somUnregisterClassLibrary
  205.                   ;
  206.  
  207.     // Class Modifiers
  208.     callstyle = oidl;
  209.     externalstem = somcm;
  210.     majorversion = 1;
  211.     minorversion = 4;
  212.     filestem = somcm;
  213.     dllname = "som.dll";
  214.  
  215.     // Attribute Modifiers
  216.     somInterfaceRepository: nodata;
  217.     somRegisteredClasses: nodata;
  218.  
  219.     // Method Modifiers
  220.     somInit: override;
  221.     somUninit: override;
  222.     somDumpSelfInt: override;
  223.  
  224.   #if defined __SOM_KERNEL_LEVEL && __SOM_KERNEL_LEVEL >= 250
  225.     somLocateClassFile: dual_owned_result;
  226.     somGetInitFunction: dual_owned_result;
  227.   #else /*__SOM_KERNEL_LEVEL 250 */
  228.     somLoadClassFile: caller_owns_parameters = "classId, file";
  229.     somLocateClassFile: caller_owns_parameters = "classId";
  230.     somRegisterClassLibrary: caller_owns_parameters = "libraryName";
  231.     somUnregisterClassLibrary: caller_owns_parameters = "libraryName";
  232.     _get_somRegisteredClasses: caller_owns_result;
  233.     somGetRelatedClasses: caller_owns_result;
  234.     somClassFromId: caller_owns_parameters = "classId";
  235.     somFindClass: caller_owns_parameters = "classId";
  236.     somFindClsInFile: caller_owns_parameters = "classId, file";
  237.     somSubstituteClass: caller_owns_parameters = "origClassName, newClassName";
  238.   #endif /*__SOM_KERNEL_LEVEL 250 */
  239.   };
  240. #endif /* __SOMIDL__ */
  241. };
  242.  
  243. #endif  /* somcm_idl */
  244.