home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / warptlk3.zip / TOOLKIT / SOM / INCLUDE / SOMCLS.IDL < prev    next >
Text File  |  1995-08-24  |  23KB  |  481 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. // SOMClass: System Object Model base metaclass
  14. // Multiple Inheritance Version
  15. #ifndef somcls_idl
  16. #define somcls_idl
  17. #include <somobj.idl>
  18. interface SOMClass : SOMObject
  19. //
  20. //  This is the SOM metaclass.  That is, the instances of this class
  21. //  are class objects.  When the SOM environment is created an instance
  22. //  of SOMClass is created and a pointer to it is placed in the external
  23. //  data location (SOMClassClassData.classObject). Bindings provide the
  24. //  macro _SOMClass for this expression. _SOMClass is unique in that it
  25. //  is its own class object. I.e., _SOMClass == _somGetClass(_SOMClass).
  26. //  SOMClass can be subclassed just like any SOM class. The subclasses
  27. //  of SOMClass are new metaclasses and can generate class objects with
  28. //  different implementations than those produced by _SOMClass.
  29. //
  30. //  An important rule for metaclass programming is that no methods
  31. //  introduced by SOMClass should ever be overridden. While this
  32. //  limits the utility of metaclass programming in SOM, it guarantees
  33. //  that SOM will operate correctly. Special class frameworks may be
  34. //  available from IBM to alleviate this restriction.
  35. //
  36. {
  37.   typedef sequence <somToken> somTokenSequence;
  38.   // a (generic) sequence of somTokens
  39.   typedef sequence <SOMClass> SOMClassSequence;
  40.   // a sequence of classes
  41.   struct somOffsetInfo {    
  42.      SOMClass cls;
  43.      long     offset;
  44.   };
  45.   // a structure to describe a class-related offset
  46.   typedef sequence <somOffsetInfo> somOffsets;
  47.   // a sequence of class-related offsets
  48.   typedef sequence <somId> somIdSequence;
  49.   // a sequence of somIds
  50.   readonly attribute long somDataAlignment;
  51.   // The alignment required for the instance data structure
  52.   // introduced by the receiving class.
  53.   readonly attribute somOffsets somInstanceDataOffsets;
  54.   // A sequence of the instance data offsets for all classes used in
  55.   // the derivation of the receiving class (including the receiver).
  56.   attribute SOMClassSequence somDirectInitClasses;
  57.   // The ancestors whose initializers the receiving 
  58.   // class wants to directly invoke.
  59.   SOMObject somNew();
  60.   // Uses SOMMalloc to allocate storage for a new instance of the
  61.   // receiving class, and then calls somRenewNoInitNoZero to load the 
  62.   // new object's method table pointer. Then somDefaultInit is called to
  63.   // initialize the new object.  Note: If the instance is a class object,
  64.   // somInitMIClass must then be invoked to declare parents and 
  65.   // initialize the class's instance method table. Upon failure, NULL
  66.   // is returned.
  67.   SOMObject somNewNoInit();
  68.   // Equivalent to somNew except that somDefaultInit is not called.
  69.   SOMObject somRenew(in void *obj);
  70.   // Equivalent to somNew except that storage is not allocated. 
  71.   // <obj> is taken as the address of the new object.
  72.   SOMObject somRenewNoInit(in void *obj);
  73.   // Equivalent to somRenew except that somDefaultInit is not called.
  74.   SOMObject somRenewNoZero(in void *obj);
  75.   // Equivalent to somRenew except that memory is not zeroed out.
  76.   SOMObject somRenewNoInitNoZero(in void *obj);
  77.   // The purpose of this method is to load an object's method table. 
  78.   // The SOM API requires that somRenewNoInitNoZero always be
  79.   // called when creating a new object whose metaclass is not SOMClass.
  80.   // This is because metaclasses must be guaranteed that they can use
  81.   // somRenewNoInitNoZero to track object creation if this is desired.
  82.   string somAllocate(in long size);
  83.   // Allocates memory to hold an object and returns a pointer to this memory.
  84.   // This is a nonstatic method, and cannot be overridden. The default
  85.   // implementation calls SOMMalloc, but a class designer can specify a
  86.   // different implementation using the somallocate modifier in IDL. The
  87.   // allocator takes the same parameters as this method.
  88.   void somDeallocate(in string memptr);
  89.   // Zeros out the method table pointer stored in the word pointed to by
  90.   // memptr, and then deallocates the block of memory pointed to by memptr.
  91.   // This is a nonstatic method and cannot be overridden. The default 
  92.   // deallocator called is SOMFree, but a class designer can specify a 
  93.   // different deallocator using the somdeallocate modifier in IDL. The
  94.   // deallocator takes the same parameters as this method.
  95.   readonly attribute somMethodProc* somClassAllocate;
  96.   // The memory allocation routine used by somAllocate. Provided in this
  97.   // form to support array allocation.
  98.   readonly attribute somMethodProc* somClassDeallocate;
  99.   // The memory allocation routine called by somDeallocate. Provided in
  100.   // this form to support array deallocation.
  101.   somBooleanVector somGetInstanceInitMask(out somInitCtrl ctrl);
  102.   // Loads a structure used to control calls to initializers.
  103.   // Computed when first requested (using the somDirectedInitClasses
  104.   // attribute) and then cached.
  105.   somBooleanVector somGetInstanceDestructionMask(out somDestructCtrl ctrl);
  106.   // Loads a structure used to control calls to somDestruct.
  107.   // Computed at the same time as somInstanceConstructionMask
  108.   somBooleanVector somGetInstanceAssignmentMask(out somAssignCtrl ctrl);
  109.   // Loads a structure used to control calls to assignment ops.
  110.   // Computed at the same time as somInstanceConstructionMask
  111.   void somInitClass(in string className, 
  112.                     in SOMClass parentClass, 
  113.                     in long dataSize, 
  114.                     in long maxStaticMethods, 
  115.                     in long majorVersion, 
  116.                     in long minorVersion);
  117. // somInitClass is obsolete, and should no longer be used. The SOM 2.0 
  118. // kernel provides special handling for redispatch stubs in the case
  119. // of SOM 1.0 classes, and use of this method is what tells the kernel
  120. // that old-style redispatch stubs will be registered.
  121.   void somInitMIClass(in long inherit_vars,
  122.                       in string className, 
  123.                       in SOMClassSequence parentClasses,
  124.                       in long dataSize, 
  125.                       in long dataAlignment,
  126.                       in long maxStaticMethods, 
  127.                       in long majorVersion, 
  128.                       in long minorVersion);
  129.   // somInitMIClass implements the second phase of dynamic class creation:
  130.   // inheritance of interface and possibly implementation (instance
  131.   // variables) by suitable initialization of <self> (a class object).
  132.   //
  133.   // For somInitMIClass, the inherit_vars argument controls whether abstract
  134.   // or implementation inheritance is used. Inherit_vars is a 32 bit
  135.   // bit-vector. Implementation is inherited from parent i iff the bit
  136.   // 1<<i is on, or i>=32.
  137.   // On a class-by-class basis, for each class ancestor, implementation
  138.   // inheritance always takes precidence over abstract inheritance. This is
  139.   // necessary to guarantee that procedures supporting parent method calls
  140.   // (available on non-abstract parents) are always supported by parent
  141.   // instance variables.
  142.   //
  143.   // <className> is a string containing the class name. A copy is made, so
  144.   // the string may be freed upon return to the caller if this is desired.
  145.   //
  146.   // <parentClasses> is a SOMClassSequence containing pointers to the
  147.   // parent classes. somInitMIClass makes a copy of this, so it may
  148.   // be freed upon return to the caller if this is desired.
  149.   //
  150.   // <dataSize> is the space needed for the instance variables
  151.   // introduced by this class.
  152.   //
  153.   // <dataAlignment> specifies the desired byte alignment for instance
  154.   // data introduced by this class. A value of 0 selects a system-wide default;
  155.   // any other argument is taken as the desired byte alignment multiple. Thus,
  156.   // for example, even if a byte multiple of 8 is needed for double precision 
  157.   // values on a given system (so 8 is the default), a class whose instance data
  158.   // doesn't require this can indicate otherwise. If A is the next memory 
  159.   // address available for holding instance data, the address that will be 
  160.   // used is A + (A mod byte-alignment).
  161.   //
  162.   // <maxStaticMethods> is the maximum number of static methods that will be
  163.   // added to the initialized class using addStaticMethod.
  164.   //
  165.   // <majorVersion> indicates the major version number for this
  166.   // implementation of the class definition, and <minorVersion>
  167.   // indicates the minor version number.
  168.   somMToken somAddStaticMethod(in somId methodId, 
  169.                                in somId methodDescriptor, 
  170.                                in somMethodPtr method, 
  171.                                in somMethodPtr redispatchStub, 
  172.                                in somMethodPtr applyStub);
  173.   // Adds the indicated method, creating and returning a new method token.
  174.   //
  175.   // <methodDescriptor> is the somId for an identifier that can be used
  176.   // to access signature information about the method from an interface
  177.   // repository.
  178.   //
  179.   // <method> is the actual method procedure for this method
  180.   //
  181.   // <redispatchStub> is a procedure with the same calling sequence as
  182.   // <method> that invokes somDispatch for the method.
  183.   //
  184.   // <applyStub> is a procedure used to support somApply. 
  185.   void somAddDynamicMethod(in somId methodId, 
  186.                            in somId methodDescriptor, 
  187.                            in somMethodPtr method, 
  188.                            in somMethodPtr applyStub);
  189.   // Adds the indicated method to the class's name lookup list.
  190.   // If this happens to override a static method then this operation is
  191.   // equivalent to <somOverrideSMethod> and the <methodDescriptor> and
  192.   // <applyStub> arguments are ignored (the overridden method's values
  193.   // will be used).
  194.   //
  195.   // <methodDescriptor> is the somId of a string describing the calling
  196.   // sequence to this method as described in <somcGetNthMethodInfo>
  197.   // defined in the SOMObject class definition.
  198.   //
  199.   // <method> is the actual method procedure for this method
  200.   //
  201.   // <applyStub> is a procedure that takes a standard variable argument
  202.   // list data structure applies it to its target object by calling
  203.   // <method> with arguments derived from the data structure.  Its
  204.   // calling sequence is the same as the calling sequence of the
  205.   // dispatch methods defined in SOMObject.  This stub is used in the
  206.   // support of the dispatch methods used in some classes.  In classes
  207.   // where the dispatch functions do not need such a function this
  208.   // parameter may be null.
  209.   void somOverrideSMethod(in somId methodId, 
  210.                           in somMethodPtr method);
  211.   // This method can be used instead of <somAddStaticMethod> or
  212.   // <somAddDynamicMethod> when it is known that the class' parent
  213.   // class already supports this method.  This call does not require the
  214.   // method descriptor and stub methods that the others do.
  215.   void somClassReady();
  216.   // This method is invoked when all of the static initialization for
  217.   // the class has been finished.  The default implementation simply
  218.   // registers the newly constructed class with the SOMClassMgr.
  219.   somMethodPtr somGetApplyStub(in somId methodId);
  220.   // Returns the apply stub associated with the specified method,
  221.   // if one exists; otherwise NULL is returned. This method is obsolete,
  222.   // and retained for binary compatability. In SOMr2, users never access
  223.   // apply stubs directly; The function somApply is used to invoke apply 
  224.   // stubs. See somApply documentation for further information on apply
  225.   // stubs, and see somAddStaticMethod documentation for information
  226.   // on how apply stubs are registered by class implementations.
  227.   somClassDataStructure *somGetClassData(); 
  228.   void somSetClassData(in somClassDataStructure cds);
  229.   // The class' pointer to the static <className>ClassData structure.
  230.   somMethodTab* somGetClassMtab();
  231.   // A pointer to the method table used by instances of this class. This
  232.   // method was misnamed; it should have been called somGetInstanceMtab.
  233.   long somGetInstanceOffset();
  234.   // Returns the offset of instance data introduced by the receiver in
  235.   // an instance of the receiver. This method is obsolete and not useful in 
  236.   // multiple-inheritance situations. The attribute somInstanceDataOffsets
  237.   // replaces this method.
  238.   long somGetInstancePartSize();
  239.   // The size in bytes of the instance data introduced by the receiving
  240.   // class.
  241.   long somGetInstanceSize();
  242.   // The total size of an instance of the receiving class.
  243.   somDToken somGetInstanceToken();
  244.   // A data token that identifies the introduced portion of this class
  245.   // within itself or any derived class.  This token can be subsequently
  246.   // passed to the run-time somDataResolve function to locate the instance
  247.   // data introduced by this class in any object derived from this class.
  248.   somDToken somGetMemberToken(in long memberOffset, 
  249.                               in somDToken instanceToken);
  250.   // Returns a data token that for the data member at offset
  251.   // "memberOffset" within the introduced portion of the class identified
  252.   // by instanceToken.  The instance token must have been obtained from a
  253.   // previous invocation of somGetInstanceToken.  The returned member
  254.   // token can be subsequently passed to the run-time somDataResolve
  255.   // function to locate the data member.
  256.   boolean somGetMethodData(in somId methodId, 
  257.                        out somMethodData md);
  258.   // Sets the fields in the method descriptor block, <md>, to
  259.   // information about the method.  1 (true) is returned if the method is
  260.   // supported by this object and 0 (false) otherwise. The id field in
  261.   // the method descriptor block will also be set to NULL.
  262.   somMethodProc *somGetRdStub(in somId methodId);
  263.   // Returns a redispatch stub for the indicated method, if possible.
  264.   // If not possible (because a valid redispatch stub has not been
  265.   // registered, and there is insufficient information to dynamically
  266.   // construct one), then a NULL is returned.
  267.   somId somGetMethodDescriptor(in somId methodId);
  268.   // Returns the method descriptor for the indicated method.    If
  269.   // this object does not support the indicated method then NULL is
  270.   // returned.
  271.   long somGetMethodIndex(in somId id);
  272.   // Returns the index for the specified method. (A number that may
  273.   // change if any methods are added or deleted to this class object or
  274.   // any of its ancestors).  This number is the basis for other calls to
  275.   // get info about the method. Indexes start at 0. A -1 is returned if
  276.   // the method cannot be found.
  277.   somMToken somGetMethodToken(in somId methodId);
  278.   // Returns the specified method's access token. This token can then
  279.   // be passed to method resolution routines, which use the token
  280.   // to select a method pointer from a method table.
  281.   string somGetName();
  282.   // This object's class name as a NULL terminated string.
  283.   boolean somGetNthMethodData(in long n, out somMethodData md);
  284.   // loads *md with the method data associated with the the nth method,
  285.   // or NULL if there is no such method. Returns true is successful;
  286.   // false otherwise.
  287.   somId somGetNthMethodInfo(in long n, 
  288.                             out somId descriptor);
  289.   // Returns the id of the <n>th method if one exists and NULL
  290.   // otherwise.
  291.   //
  292.   // The ordering of the methods is unpredictable, but will not change
  293.   // unless some change is made to the class or one of its ancestor classes.
  294.   //
  295.   // See CORBA documentation for info on method descriptors.
  296.   long somGetNumMethods();
  297.   // The number of methods currently supported by this class,
  298.   // including inherited methods (both static and dynamic).
  299.   long somGetNumStaticMethods();
  300.   // The number of static methods that this class has.  Can
  301.   // be used by a child class when initializing its method table.
  302.   SOMClass somGetParent();
  303.   // Returns the parent class of self (along its "left-hand" derivation
  304.   // path), if one exists and NULL otherwise.
  305.   SOMClassSequence somGetParents();
  306.   // The parent classes of self.
  307.   somMethodTabs somGetPClsMtab();
  308.   // Returns a list of the method tables of this class's parent classes in the
  309.   // specific format required by somParentNumResolve (for making parent method
  310.   // calls. The first entry on the list is actually the method table of the
  311.   // receiving class. Because the CClassData structure contains this list, the
  312.   // method table for any class with a CClassData structure is statically 
  313.   // available. This method now returns a list because older SI emitters load 
  314.   // CClassData.parentMtab with the result of this call, and the new runtime 
  315.   // requires a list of classes in that position.
  316.   somMethodTabs somGetPClsMtabs();
  317.   // Returns a list of the method tables of this class's parent classes in the
  318.   // specific format required by somParentNumResolve (for making parent method
  319.   // calls. The first entry on the list is actually the method table of the
  320.   // receiving class. Because the CClassData structure contains this list, the
  321.   // method table for any class with a CClassData structure is statically 
  322.   // available.
  323.   void somGetVersionNumbers (out long majorVersion, out long minorVersion);
  324.   // Returns the class' major and minor version numbers in the corresponding
  325.   // output parameters.
  326.   boolean somSetMethodDescriptor(in somId methodId, 
  327.                                  in somId descriptor);
  328.   // Sets the method descriptor given by <descriptor> for the method
  329.   // <methodId> into the method information kept by the receiving class.
  330.   // 1 (true) is returned if the method is supported by this object
  331.   // and 0 (false) otherwise.
  332.   boolean somFindMethod(in somId methodId, 
  333.                         out somMethodPtr m);
  334.   // Finds the method procedure associated with <methodId> for this
  335.   // class and sets <m> to it.  1 (true) is returned when the
  336.   // method procedure is a static method and 0 (false) is returned
  337.   // when the method procedure is dynamic method.
  338.   //
  339.   // If the class does not support the specified method then
  340.   // <m> is set to NULL and the return value is meaningless.
  341.   //
  342.   boolean somFindMethodOk(in somId methodId, 
  343.                           out somMethodPtr m);
  344.   // Just like <somFindMethod> except that if the method is not
  345.   // supported then an error is raised and execution is halted.
  346.   somMethodPtr somFindSMethod(in somId methodId);
  347.   // Finds the indicated method, which must be a static method supported
  348.   // by this class, and returns a pointer to its method procedure.
  349.   // If the method is not supported by the receiver (as a static method 
  350.   // or at all) then a NULL pointer is returned.
  351.   somMethodPtr somFindSMethodOk(in somId methodId);
  352.   // Uses <somFindSMethod>, and raises an error if the result is NULL.
  353.   somMethodPtr somLookupMethod(in somId methodId);
  354.   // Like <somFindSMethodOK>, but without restriction to static methods.
  355.   boolean somCheckVersion(in long majorVersion, 
  356.                           in long minorVersion);
  357.   // Returns 1 (true) if the implementation of this class is
  358.   // compatible with the specified major and minor version number and
  359.   // false (0) otherwise.  An implementation is compatible with the
  360.   // specified version numbers if it has the same major version number
  361.   // and a minor version number that is equal to or greater than
  362.   // <minorVersion>.    The major, minor version number pair (0,0) is
  363.   // considered to match any version.  This method is usually called
  364.   // immediately after creating the class object to verify that a
  365.   // dynamically loaded class definition is compatible with a using
  366.   // application.
  367.   boolean somDescendedFrom(in SOMClass aClassObj);
  368.   // Returns 1 (true) if <self> is a descendent class of <aClassObj> and
  369.   // 0 (false) otherwise.  Note: a class object is considered to be
  370.   // descended itself for the purposes of this method.
  371.   boolean somSupportsMethod(in somId mId);
  372.   // Returns 1 (true) if the indicated method is supported by this
  373.   // class and 0 (false) otherwise.
  374.   somMethodPtr somDefinedMethod(in somMToken method);
  375.   // if the receiving class either introduces or overrides the 
  376.   // indicated method, then its somMethodPtr is returned, otherwise
  377.   // NULL is returned.
  378.   void somOverrideMtab();
  379.   // Overrides the method table pointers to point to the redispatch stubs.
  380.   // All the methods except somDispatch methods are overriden.
  381. #ifdef __SOMIDL__
  382.   implementation {
  383.     releaseorder: 
  384.         somNew,
  385.         somRenew,
  386.         somInitClass,
  387.         somClassReady,
  388.         somGetName, 
  389.         somGetParent,
  390.         somDescendedFrom,
  391.         somCheckVersion,
  392.         somFindMethod, 
  393.         somFindMethodOk,
  394.         somSupportsMethod,
  395.         somGetNumMethods, 
  396.         somGetInstanceSize,
  397.         somGetInstanceOffset,
  398.         somGetInstancePartSize,
  399.         somGetMethodIndex, 
  400.         somGetNumStaticMethods,
  401.         somGetPClsMtab, 
  402.         somGetClassMtab,
  403.         somAddStaticMethod,
  404.         somOverrideSMethod, 
  405.         somAddDynamicMethod,
  406.         somcPrivate0,
  407.         somGetApplyStub,
  408.         somFindSMethod,
  409.         somFindSMethodOk,
  410.         somGetMethodDescriptor, 
  411.         somGetNthMethodInfo,
  412.         somSetClassData,
  413.         somGetClassData, 
  414.         somNewNoInit,
  415.         somRenewNoInit,
  416.         somGetInstanceToken, 
  417.         somGetMemberToken,
  418.         somSetMethodDescriptor,
  419.         somGetMethodData, 
  420.         somOverrideMtab,
  421.         somGetMethodToken,
  422.         somGetParents, 
  423.         somGetPClsMtabs,
  424.         somInitMIClass,
  425.         somGetVersionNumbers,
  426.         somLookupMethod,
  427.         _get_somInstanceDataOffsets,
  428.         somRenewNoZero, 
  429.         somRenewNoInitNoZero,
  430.         somAllocate,
  431.         somDeallocate,
  432.         somGetRdStub, 
  433.         somGetNthMethodData, 
  434.         somcPrivate1,
  435.                 somcPrivate2,
  436.         _get_somDirectInitClasses,
  437.         _set_somDirectInitClasses, 
  438.         somGetInstanceInitMask, 
  439.         somGetInstanceDestructionMask,
  440.         somcPrivate3, 
  441.         somcPrivate4,
  442.         somcPrivate5, 
  443.         somcPrivate6, 
  444.         somcPrivate7,
  445.         somDefinedMethod, 
  446.         somcPrivate8, 
  447.         somcPrivate9, 
  448.         somcPrivate10,
  449.         somcPrivate11,
  450.         somcPrivate12,
  451.         somcPrivate13,
  452.         somcPrivate14,
  453.         somcPrivate15,
  454.         _get_somDataAlignment, somGetInstanceAssignmentMask, 
  455.         somcPrivate16, 
  456.         somcPrivate17,
  457.         _get_somClassAllocate, _get_somClassDeallocate;
  458.     // Class Modifiers
  459.     callstyle = oidl;
  460.     externalstem = sommc; 
  461.     majorversion = 1; 
  462.     minorversion = 4; 
  463.     filestem = somcls;
  464.     dllname = "som.dll";
  465.     // Attribute Modifiers
  466.     somInstanceDataOffsets: nodata, nonstatic;
  467.     somMethodOffsets: nodata, nonstatic;
  468.     somDirectAssignClasses: noget, nonstatic;
  469.     somDirectInitClasses: noset, nonstatic;
  470.     somClassDataOrder: noset, nonstatic;
  471.     // Method Modifiers
  472.     somClassOfNewClassWithParents: procedure, noself;
  473.     somAllocate: nonstatic;
  474.     somDeallocate: nonstatic;
  475.     _get_somClassAllocate: nonstatic;
  476.     _get_somClassDeallocate: nonstatic;
  477.     };
  478. #endif /* __SOMIDL__ */
  479. };
  480. #endif  /* somcls_idl */
  481.