// @(#)44	1.2  src/somk/somcls.idl, somk.sc, som2.1.1 12/13/94 10:42:58
//
//   COMPONENT_NAME: somk
//
//   ORIGINS: 27
//
//
//   10H9767, 10H9769  (C) COPYRIGHT International Business Machines Corp. 1994
//   All Rights Reserved
//   Licensed Materials - Property of IBM
//   US Government Users Restricted Rights - Use, duplication or
//   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
//
// SOMClass: System Object Model base metaclass
// Multiple Inheritance Version
#ifndef somcls_idl
#define somcls_idl
#include <somobj.idl>
interface SOMClass : SOMObject
//
//  This is the SOM metaclass.  That is, the instances of this class
//  are class objects.  When the SOM environment is created an instance
//  of SOMClass is created and a pointer to it is placed in the external
//  data location (SOMClassClassData.classObject). Bindings provide the
//  macro _SOMClass for this expression. _SOMClass is unique in that it
//  is its own class object. I.e., _SOMClass == _somGetClass(_SOMClass).
//  SOMClass can be subclassed just like any SOM class. The subclasses
//  of SOMClass are new metaclasses and can generate class objects with
//  different implementations than those produced by _SOMClass.
//
//  An important rule for metaclass programming is that no methods
//  introduced by SOMClass should ever be overridden. While this
//  limits the utility of metaclass programming in SOM, it guarantees
//  that SOM will operate correctly. Special class frameworks may be
//  available from IBM to alleviate this restriction.
//
{
  typedef sequence <somToken> somTokenSequence;
  // a (generic) sequence of somTokens
  typedef sequence <SOMClass> SOMClassSequence;
  // a sequence of classes
  struct somOffsetInfo {	
     SOMClass cls;
     long     offset;
  };
  // a structure to describe a class-related offset
  typedef sequence <somOffsetInfo> somOffsets;
  // a sequence of class-related offsets
  typedef sequence <somId> somIdSequence;
  // a sequence of somIds
  readonly attribute long somDataAlignment;
  // The alignment required for the instance data structure
  // introduced by the receiving class.
  readonly attribute somOffsets somInstanceDataOffsets;
  // A sequence of the instance data offsets for all classes used in
  // the derivation of the receiving class (including the receiver).
  attribute SOMClassSequence somDirectInitClasses;
  // The ancestors whose initializers the receiving 
  // class wants to directly invoke.
  SOMObject somNew();
  // Uses SOMMalloc to allocate storage for a new instance of the
  // receiving class, and then calls somRenewNoInitNoZero to load the 
  // new object's method table pointer. Then somDefaultInit is called to
  // initialize the new object.  Note: If the instance is a class object,
  // somInitMIClass must then be invoked to declare parents and 
  // initialize the class's instance method table. Upon failure, NULL
  // is returned.
  SOMObject somNewNoInit();
  // Equivalent to somNew except that somDefaultInit is not called.
  SOMObject somRenew(in void *obj);
  // Equivalent to somNew except that storage is not allocated. 
  // <obj> is taken as the address of the new object.
  SOMObject somRenewNoInit(in void *obj);
  // Equivalent to somRenew except that somDefaultInit is not called.
  SOMObject somRenewNoZero(in void *obj);
  // Equivalent to somRenew except that memory is not zeroed out.
  SOMObject somRenewNoInitNoZero(in void *obj);
  // The purpose of this method is to load an object's method table. 
  // The SOM API requires that somRenewNoInitNoZero always be
  // called when creating a new object whose metaclass is not SOMClass.
  // This is because metaclasses must be guaranteed that they can use
  // somRenewNoInitNoZero to track object creation if this is desired.
  string somAllocate(in long size);
  // Allocates memory to hold an object and returns a pointer to this memory.
  // The default implementation for somAllocate (used by SOMClass) is to 
  // access default memory allocation through the external procedure 
  // variable, SOMMalloc. This method must allocate at least 4 bytes. Upon
  // failure, NULL is returned. This is nonstatic method, and cannot be
  // overridden. 
  void somDeallocate(in string memptr);
  // Deallocates object memory originally allocated using somAllocate, and
  // nulls out the method table pointer in the first word of the object. The 
  // implementation for somDeallocate used by SOMClass is to access default
  // memory deallocation from the external procedure variable, SOMFree. This
  // is a nonstatic method, and cannot be overridden.
  somBooleanVector somGetInstanceInitMask(out somInitCtrl ctrl);
  // Loads a structure used to control calls to initializers.
  // Computed when first requested (using the somDirectedInitClasses
  // attribute) and then cached.
  somBooleanVector somGetInstanceDestructionMask(out somDestructCtrl ctrl);
  // Loads a structure used to control calls to somDestruct.
  // Computed at the same time as somInstanceConstructionMask
  somBooleanVector somGetInstanceAssignmentMask(out somAssignCtrl ctrl);
  // Loads a structure used to control calls to assignment ops.
  // Computed at the same time as somInstanceConstructionMask
  void somInitClass(in string className, 
                    in SOMClass parentClass, 
                    in long dataSize, 
                    in long maxStaticMethods, 
                    in long majorVersion, 
                    in long minorVersion);
// somInitClass is obsolete, and should no longer be used. The SOM 2.0 
// kernel provides special handling for redispatch stubs in the case
// of SOM 1.0 classes, and use of this method is what tells the kernel
// that old-style redispatch stubs will be registered.
  void somInitMIClass(in long inherit_vars,
                      in string className, 
                      in SOMClassSequence parentClasses,
                      in long dataSize, 
                      in long dataAlignment,
                      in long maxStaticMethods, 
                      in long majorVersion, 
                      in long minorVersion);
  // somInitMIClass implements the second phase of dynamic class creation:
  // inheritance of interface and possibly implementation (instance
  // variables) by suitable initialization of <self> (a class object).
  //
  // For somInitMIClass, the inherit_vars argument controls whether abstract
  // or implementation inheritance is used. Inherit_vars is a 32 bit
  // bit-vector. Implementation is inherited from parent i iff the bit
  // 1<<i is on, or i>=32.
  // On a class-by-class basis, for each class ancestor, implementation
  // inheritance always takes precidence over abstract inheritance. This is
  // necessary to guarantee that procedures supporting parent method calls
  // (available on non-abstract parents) are always supported by parent
  // instance variables.
  //
  // <className> is a string containing the class name. A copy is made, so
  // the string may be freed upon return to the caller if this is desired.
  //
  // <parentClasses> is a SOMClassSequence containing pointers to the
  // parent classes. somInitMIClass makes a copy of this, so it may
  // be freed upon return to the caller if this is desired.
  //
  // <dataSize> is the space needed for the instance variables
  // introduced by this class.
  //
  // <dataAlignment> specifies the desired byte alignment for instance
  // data introduced by this class. A value of 0 selects a system-wide default;
  // any other argument is taken as the desired byte alignment multiple. Thus,
  // for example, even if a byte multiple of 8 is needed for double precision 
  // values on a given system (so 8 is the default), a class whose instance data
  // doesn't require this can indicate otherwise. If A is the next memory 
  // address available for holding instance data, the address that will be 
  // used is A + (A mod byte-alignment).
  //
  // <maxStaticMethods> is the maximum number of static methods that will be
  // added to the initialized class using addStaticMethod.
  //
  // <majorVersion> indicates the major version number for this
  // implementation of the class definition, and <minorVersion>
  // indicates the minor version number.
  somMToken somAddStaticMethod(in somId methodId, 
                               in somId methodDescriptor, 
                               in somMethodPtr method, 
                               in somMethodPtr redispatchStub, 
                               in somMethodPtr applyStub);
  // Adds the indicated method, creating and returning a new method token.
  //
  // <methodDescriptor> is the somId for an identifier that can be used
  // to access signature information about the method from an interface
  // repository.
  //
  // <method> is the actual method procedure for this method
  //
  // <redispatchStub> is a procedure with the same calling sequence as
  // <method> that invokes somDispatch for the method.
  //
  // <applyStub> is a procedure used to support somApply. 
  void somAddDynamicMethod(in somId methodId, 
                           in somId methodDescriptor, 
                           in somMethodPtr method, 
                           in somMethodPtr applyStub);
  // Adds the indicated method to the class's name lookup list.
  // If this happens to override a static method then this operation is
  // equivalent to <somOverrideSMethod> and the <methodDescriptor> and
  // <applyStub> arguments are ignored (the overridden method's values
  // will be used).
  //
  // <methodDescriptor> is the somId of a string describing the calling
  // sequence to this method as described in <somcGetNthMethodInfo>
  // defined in the SOMObject class definition.
  //
  // <method> is the actual method procedure for this method
  //
  // <applyStub> is a procedure that takes a standard variable argument
  // list data structure applies it to its target object by calling
  // <method> with arguments derived from the data structure.  Its
  // calling sequence is the same as the calling sequence of the
  // dispatch methods defined in SOMObject.  This stub is used in the
  // support of the dispatch methods used in some classes.  In classes
  // where the dispatch functions do not need such a function this
  // parameter may be null.
  void somOverrideSMethod(in somId methodId, 
                          in somMethodPtr method);
  // This method can be used instead of <somAddStaticMethod> or
  // <somAddDynamicMethod> when it is known that the class' parent
  // class already supports this method.  This call does not require the
  // method descriptor and stub methods that the others do.
  void somClassReady();
  // This method is invoked when all of the static initialization for
  // the class has been finished.  The default implementation simply
  // registers the newly constructed class with the SOMClassMgr.
  somMethodPtr somGetApplyStub(in somId methodId);
  // Returns the apply stub associated with the specified method,
  // if one exists; otherwise NULL is returned. This method is obsolete,
  // and retained for binary compatability. In SOMr2, users never access
  // apply stubs directly; The function somApply is used to invoke apply 
  // stubs. See somApply documentation for further information on apply
  // stubs, and see somAddStaticMethod documentation for information
  // on how apply stubs are registered by class implementations.
  somClassDataStructure *somGetClassData(); 
  void somSetClassData(in somClassDataStructure cds);
  // The class' pointer to the static <className>ClassData structure.
  somMethodTab* somGetClassMtab();
  // A pointer to the method table used by instances of this class. This
  // method was misnamed; it should have been called somGetInstanceMtab.
  long somGetInstanceOffset();
  // Returns the offset of instance data introduced by the receiver in
  // an instance of the receiver. This method is obsolete and not useful in 
  // multiple-inheritance situations. The attribute somInstanceDataOffsets
  // replaces this method.
  long somGetInstancePartSize();
  // The size in bytes of the instance data introduced by the receiving
  // class.
  long somGetInstanceSize();
  // The total size of an instance of the receiving class.
  somDToken somGetInstanceToken();
  // A data token that identifies the introduced portion of this class
  // within itself or any derived class.  This token can be subsequently
  // passed to the run-time somDataResolve function to locate the instance
  // data introduced by this class in any object derived from this class.
  somDToken somGetMemberToken(in long memberOffset, 
                              in somDToken instanceToken);
  // Returns a data token that for the data member at offset
  // "memberOffset" within the introduced portion of the class identified
  // by instanceToken.  The instance token must have been obtained from a
  // previous invocation of somGetInstanceToken.  The returned member
  // token can be subsequently passed to the run-time somDataResolve
  // function to locate the data member.
  boolean somGetMethodData(in somId methodId, 
                       out somMethodData md);
  // Sets the fields in the method descriptor block, <md>, to
  // information about the method.  1 (true) is returned if the method is
  // supported by this object and 0 (false) otherwise. The id field in
  // the method descriptor block will also be set to NULL.
  somMethodProc *somGetRdStub(in somId methodId);
  // Returns a redispatch stub for the indicated method, if possible.
  // If not possible (because a valid redispatch stub has not been
  // registered, and there is insufficient information to dynamically
  // construct one), then a NULL is returned.
  somId somGetMethodDescriptor(in somId methodId);
  // Returns the method descriptor for the indicated method.	If
  // this object does not support the indicated method then NULL is
  // returned.
  long somGetMethodIndex(in somId id);
  // Returns the index for the specified method. (A number that may
  // change if any methods are added or deleted to this class object or
  // any of its ancestors).  This number is the basis for other calls to
  // get info about the method. Indexes start at 0. A -1 is returned if
  // the method cannot be found.
  somMToken somGetMethodToken(in somId methodId);
  // Returns the specified method's access token. This token can then
  // be passed to method resolution routines, which use the token
  // to select a method pointer from a method table.
  string somGetName();
  // This object's class name as a NULL terminated string.
  boolean somGetNthMethodData(in long n, out somMethodData md);
  // loads *md with the method data associated with the the nth method,
  // or NULL if there is no such method. Returns true is successful;
  // false otherwise.
  somId somGetNthMethodInfo(in long n, 
                            out somId descriptor);
  // Returns the id of the <n>th method if one exists and NULL
  // otherwise.
  //
  // The ordering of the methods is unpredictable, but will not change
  // unless some change is made to the class or one of its ancestor classes.
  //
  // See CORBA documentation for info on method descriptors.
  long somGetNumMethods();
  // The number of methods currently supported by this class,
  // including inherited methods (both static and dynamic).
  long somGetNumStaticMethods();
  // The number of static methods that this class has.  Can
  // be used by a child class when initializing its method table.
  SOMClass somGetParent();
  // Returns the parent class of self (along its "left-hand" derivation
  // path), if one exists and NULL otherwise.
  SOMClassSequence somGetParents();
  // The parent classes of self.
  somMethodTabs somGetPClsMtab();
  // Returns a list of the method tables of this class's parent classes in the
  // specific format required by somParentNumResolve (for making parent method
  // calls. The first entry on the list is actually the method table of the
  // receiving class. Because the CClassData structure contains this list, the
  // method table for any class with a CClassData structure is statically 
  // available. This method now returns a list because older SI emitters load 
  // CClassData.parentMtab with the result of this call, and the new runtime 
  // requires a list of classes in that position.
  somMethodTabs somGetPClsMtabs();
  // Returns a list of the method tables of this class's parent classes in the
  // specific format required by somParentNumResolve (for making parent method
  // calls. The first entry on the list is actually the method table of the
  // receiving class. Because the CClassData structure contains this list, the
  // method table for any class with a CClassData structure is statically 
  // available.
  void somGetVersionNumbers (out long majorVersion, out long minorVersion);
  // Returns the class' major and minor version numbers in the corresponding
  // output parameters.
  boolean somSetMethodDescriptor(in somId methodId, 
                                 in somId descriptor);
  // Sets the method descriptor given by <descriptor> for the method
  // <methodId> into the method information kept by the receiving class.
  // 1 (true) is returned if the method is supported by this object
  // and 0 (false) otherwise.
  boolean somFindMethod(in somId methodId, 
                        out somMethodPtr m);
  // Finds the method procedure associated with <methodId> for this
  // class and sets <m> to it.  1 (true) is returned when the
  // method procedure is a static method and 0 (false) is returned
  // when the method procedure is dynamic method.
  //
  // If the class does not support the specified method then
  // <m> is set to NULL and the return value is meaningless.
  //
  boolean somFindMethodOk(in somId methodId, 
                          out somMethodPtr m);
  // Just like <somFindMethod> except that if the method is not
  // supported then an error is raised and execution is halted.
  somMethodPtr somFindSMethod(in somId methodId);
  // Finds the indicated method, which must be a static method supported
  // by this class, and returns a pointer to its method procedure.
  // If the method is not supported by the receiver (as a static method 
  // or at all) then a NULL pointer is returned.
  somMethodPtr somFindSMethodOk(in somId methodId);
  // Uses <somFindSMethod>, and raises an error if the result is NULL.
  somMethodPtr somLookupMethod(in somId methodId);
  // Like <somFindSMethodOK>, but without restriction to static methods.
  boolean somCheckVersion(in long majorVersion, 
                          in long minorVersion);
  // Returns 1 (true) if the implementation of this class is
  // compatible with the specified major and minor version number and
  // false (0) otherwise.  An implementation is compatible with the
  // specified version numbers if it has the same major version number
  // and a minor version number that is equal to or greater than
  // <minorVersion>.	The major, minor version number pair (0,0) is
  // considered to match any version.  This method is usually called
  // immediately after creating the class object to verify that a
  // dynamically loaded class definition is compatible with a using
  // application.
  boolean somDescendedFrom(in SOMClass aClassObj);
  // Returns 1 (true) if <self> is a descendent class of <aClassObj> and
  // 0 (false) otherwise.  Note: a class object is considered to be
  // descended itself for the purposes of this method.
  boolean somSupportsMethod(in somId mId);
  // Returns 1 (true) if the indicated method is supported by this
  // class and 0 (false) otherwise.
  somMethodPtr somDefinedMethod(in somMToken method);
  // if the receiving class either introduces or overrides the 
  // indicated method, then its somMethodPtr is returned, otherwise
  // NULL is returned.
  void somOverrideMtab();
  // Overrides the method table pointers to point to the redispatch stubs.
  // All the methods except somDispatch methods are overriden.
#ifdef __SOMIDL__
  implementation {
    releaseorder: 
		somNew,
		somRenew,
		somInitClass,
		somClassReady,
		somGetName, 
		somGetParent,
		somDescendedFrom,
		somCheckVersion,
		somFindMethod, 
		somFindMethodOk,
		somSupportsMethod,
		somGetNumMethods, 
		somGetInstanceSize,
		somGetInstanceOffset,
		somGetInstancePartSize,
		somGetMethodIndex, 
		somGetNumStaticMethods,
		somGetPClsMtab, 
		somGetClassMtab,
		somAddStaticMethod,
		somOverrideSMethod, 
		somAddDynamicMethod,
		somcPrivate0,
		somGetApplyStub,
		somFindSMethod,
		somFindSMethodOk,
		somGetMethodDescriptor, 
		somGetNthMethodInfo,
		somSetClassData,
		somGetClassData, 
		somNewNoInit,
		somRenewNoInit,
		somGetInstanceToken, 
		somGetMemberToken,
		somSetMethodDescriptor,
		somGetMethodData, 
		somOverrideMtab,
		somGetMethodToken,
		somGetParents, 
		somGetPClsMtabs,
		somInitMIClass,
		somGetVersionNumbers,
		somLookupMethod,
		_get_somInstanceDataOffsets,
		somRenewNoZero, 
		somRenewNoInitNoZero,
		somAllocate,
		somDeallocate,
		somGetRdStub, 
		somGetNthMethodData, 
		somcPrivate1,
                somcPrivate2,
		_get_somDirectInitClasses,
		_set_somDirectInitClasses, 
		somGetInstanceInitMask, 
		somGetInstanceDestructionMask,
		somcPrivate3, 
		somcPrivate4,
		somcPrivate5, 
		somcPrivate6, 
		somcPrivate7,
		somDefinedMethod, 
		somcPrivate8, 
		somcPrivate9, 
		somcPrivate10,
		somcPrivate11,
		somcPrivate12,
		somcPrivate13,
		somcPrivate14,
		somcPrivate15,
		_get_somDataAlignment, somGetInstanceAssignmentMask, 
		somcPrivate16, 
		somcPrivate17;
    // Class Modifiers
    callstyle = oidl;
    externalstem = sommc; 
    majorversion = 1; 
    minorversion = 4; 
    filestem = somcls;
    dllname = "som.dll";
    // Attribute Modifiers
    somInstanceDataOffsets: nodata;
    somMethodOffsets: nodata;
    somDirectAssignClasses: noget;
    somDirectInitClasses: noset;
    somClassDataOrder: noset;
    // Method Modifiers
    somClassOfNewClassWithParents: procedure, noself;
    somAllocate: nonstatic;
    somDeallocate: nonstatic;
    };
#endif /* __SOMIDL__ */
};
#endif  /* somcls_idl */
