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