//#  @(#) 1.53 src/somk/somcls.idl, somk.sc, som3.0 6/13/96 10:37:49 [12/22/96 21:12:47]

// 96F8647, 96F8648, 96F8850 (C) Copyright IBM Corp. 1992, 1994
// All Rights Reserved
// Licensed Materials - Property of IBM

// SOMClass: System Object Model base metaclass
// Multiple Inheritance Version

#ifndef somcls_idl
#define somcls_idl


#include <somobj.idl>

typedef somToken somCClassDataStructurePtr;
typedef somToken somClassDataStructurePtr;
typedef somToken somMethodTabPtr;
typedef somToken somEmbeddedObjStructPtr;
typedef somToken somMethodDefnPtr;
typedef somToken somClassMemPtr;
typedef somToken somClassVars3Ptr;
typedef somToken SOM_CIBPtr;


interface SOMClass : SOMObject
//
//  SOMClass is the root SOM metaclass. Because it is a metaclass, its
//  instances are classes. Because it is the root metaclass, all other
//  metaclasses inherit its methods.
//
//  SOMClass defines the default behavior for SOM class objects
//  accessed using methods available through the SOMClass interface.
//  Other metaclasses are allowed to specialize the behavior of
//  classes by introducing new methods and overriding SOMClass
//  methods.
//
//  Generally, when SOMClass methods are overridden by user-defined
//  metaclasses, a relative parent call should be made at some point to
//  allow the default behavior implemented by SOMClass to execute
//  (in addition to whatever additional behavior might be desired by the
//  new metaclasses).
//
//# SOMLEGACY1 concerns obsolete but supported SOM 1.0 APIs.
{

  //############  [Typedefs] ##############

  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



  //############   [Instance Creation/Renewal]   ############

  SOMObject somNew();
  // Uses somAllocate to allocate storage for a new
  // instance of the receiving class, calls somRenewNoInitNoZero
  // to load the new object's method table pointer, and then
  // calls somDefaultInit to initialize the new object.
  // Overrides are not expected. NULL is returned on failure.

  SOMObject somNewNoInit();
  // Equivalent to somNew except that somDefaultInit is not called.
  // Overrides are not expected.

  SOMObject somRenew(in void *obj);
  // Equivalent to somNew except that storage is not allocated.
  // <obj> is taken as the address of the new object.
  // Overrides are not expected.

  SOMObject somRenewNoInit(in void *obj);
  // Equivalent to somRenew except that somDefaultInit is not called.
  // Overrides are not expected.

  SOMObject somRenewNoZero(in void *obj);
  // Equivalent to somRenew except that memory is not zeroed out.
  // Overrides are not expected.

  SOMObject somRenewNoInitNoZero(in void *obj);
  // This method loads an object's method table pointer, turning raw
  // memory into an uninitialized SOM object. The other somNew and
  // somRenew methods all call this method, so metaclasses can override
  // this method to track object creation if this is desired. A relative
  // parent call should be done from overrides.

  somToken somAllocate(in long size); // nonstatic
  // Uses the memory allocation routine associated with the receiving
  // class to allocate memory to hold an object of the indicated size.
  // NULL is returned on failure. The default allocation routine uses
  // SOMMalloc.

  void somDeallocate(in somToken memptr); // nonstatic
  // Uses the memory deallocation routine associated with the receiving
  // class to deallocate memory beginning at the address indicated by
  // memptr. The first word of this memory (normally a method table
  // pointer) is loaded with NULL. The deallocation routine receives
  // a void* (memptr) and a size_t (size) as arguments.


  SOMClass somJoin( in SOMClass secondParent, in string nameOfNewClass );
  // Creates the multiple inheritance join of the target class and the 
  // secondParent with the class name nameOfNewClass.

  SOMClass somEndow( in SOMClass parent, in string nameOfNewClass );
  // Creates the a subclass of parent with the class name nameOfNewClass
  // where the target class is an added metaclass constraint.
  // NOTE: this means that the target class must be a metaclass.



  //############### [Class Initialization/Termination] ###############

  SOMClass somClassOfNewClassWithParents(in string newClassName,
                                         in SOMClassSequence parents,
                                         in SOMClass explicitMeta);
  // procedure
  // returns a metaclass appropriate for use as the class of a new
  // class with the given parents and explicit metaclass.


  void somInitMIClass(in unsigned long inherit_vars,
                      in string className,
                      in SOMClassSequence parentClasses,
                      in long dataSize,
                      in long dataAlignment,
                      in long maxNDMethods,
                      in long majorVersion,
                      in long minorVersion);
  // Perform inheritance into a class object from the specified parent
  // classes, determine the layout of instances for the receiving class, and
  // determine the layout of the instance method table for the receiving class.
  // Overrides should perform relative parent calls.

  somMToken somAddStaticMethod(in somId methodId,
                               in somId methodDescriptor,
                               in somMethodPtr method,
                               in somMethodPtr redispatchStub,
                               in somMethodPtr applyStub);

  // Introduce a new static method with the indicated methodId into
  // the receiving class. Overrides should perform relative parent calls.

  void somOverrideSMethod(in somId methodId,
                          in somMethodPtr method);
  // Replace the implementation for the indicated method in the instances
  // of the receiving class. Overrides should perform relative parent calls.


  void somClassReady();
  // This method is invoked when all of the static initialization for
  // the class has been finished (i.e., its instance method table has
  // been loaded) and allows final setup for the class to be done. When
  // overriding this method, all setup should be done before doing a
  // relative pcall, since SOMClass's implementation will register the
  // class with the class manager.

  void somAddDynamicMethod(in somId methodId,
                           in somId methodDescriptor,
                           in somMethodPtr methodImpl,
                           in somMethodPtr applyStub);
  // If the receiving class supports a static method with the indicated
  // methodId, then override the method with the indicated implementation.
  // Otherwise, a dynamic method with the indicated methodId is added to
  // the receiving class.



#ifdef SOMLEGACY1
#endif


  //############ [Class Information]  ############

  string somGetName();
  // This object's class name as a NULL terminated string.
  // Overrides are not expected.

  void somGetVersionNumbers (out long majorVersion, out long minorVersion);
  // Returns the class' major and minor version numbers in the corresponding
  // output parameters.
  // Overrides are not expected.

  long somGetNumMethods();
  // The number of methods currently supported by this class,
  // including inherited methods (static, nonstatic, and dynamic).
  // Overrides are not expected.

  long somGetNumStaticMethods();
  // The number of nondynamic methods that this class has.  Can
  // be used by a child class when initializing its method table.
  // Overrides are not expected.

  SOMClassSequence somGetParents();
  // Returns a sequence containing pointers to the receiver's parent classes.
  // Caller is responsible for using SOMFree on the returned sequence buffer.
  // Overrides are not expected.

  long somGetInstanceSize();
  // The total size of an instance of the receiving class.
  // Overrides are not expected.

  long somGetInstancePartSize();
  // The size in bytes of the instance data introduced by the receiving
  // class.
  // Overrides are not expected.

  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.
  // Overrides are not expected.

  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.
  // Overrides are not expected.

  somMethodTab* somGetClassMtab();
  // A pointer to the method table used by instances of this class. This
  // method was misnamed; it should have been called somGetInstanceMtab.
  // Overrides are not expected.

  somClassDataStructurePtr somGetClassData();
  void somSetClassData(in somClassDataStructurePtr cds);
  // The pointer to the static <className>ClassData structure.
  // Overrides are not expected.

  readonly attribute long somDataAlignment;
  // The alignment required for the instance data structure
  // introduced by the receiving class.
  // Overrides are not expected.

  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).
  // The caller is responsible for freeing the returned sequence buffer.
  // Overrides are not expected.

  readonly attribute SOMClassSequence somDirectInitClasses;
  // The ancestors whose initializers the receiving class wants to
  // directly invoke. Caller is responsible for freeing the returned
  // sequence buffer.
  // Overrides are not expected.


  //####### [Method Information] #########

  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.
  // Overrides are not expected.

  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.
  // Overrides are not expected.

  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.
  // Overrides are not expected.

  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.
  // Overrides are not expected.

  somToken somGetMarshalPlan(in somId methodId);
  // uses namelookup from the target class to locate a method that has the
  // indicated methodId, and returns that method's marshal plan if there
  // is one. Otherwise, null is returned.
  // Overrides are not expected.


  //########### Method Resolution ###############

  boolean somGetMethodData(in somId methodId,
                       out somMethodData md);
  // If the receiving class supports a method with the specified somId,
  // then the method data pointed to by md is loaded with information
  // for the method and 1 (TRUE) is returned. Otherwise md->id is set to
  // NULL and 0 (FALSE) is returned. On success, the md->method field is
  // loaded with a the address of a function that invokes the method
  // implementation appropriate for instances of the receiving class.
  // Successive calls for the same method are *not* guaranteed to load
  // md->method with the same address. All somId-based method resolution
  // routines use the md->method address computed by somGetMethodData
  // as their resolution result.


  boolean somGetNthMethodData(in long n, out somMethodData md);
  // This method is similar to somGetMethodData. The method
  // whose data is returned is the method for which the receiving
  // class would return n from somGetMethodIndex.

  boolean somFindMethod(in somId methodId,
                        out somMethodPtr m);
  // If the receiving class supports a method with the specified
  // methodId, m is set to the address of a function that
  // will invoke the method implementation appropriate for instances
  // of the receiving class and 1 (TRUE) is returned. Otherwise, m is
  // set to NULL and 0 (FALSE) is returned. Successive calls on the
  // same class with the same arguments are not guaranteed to return
  // the same function address.
  // Overrides are not expected.

  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.
  // Overrides are not expected.

  somMethodPtr somFindSMethod(in somId methodId);
  // Finds the indicated method, which must be a static method supported
  // by this class, and returns a pointer to a function that will
  // invoke the method implementation appropriate for instances of the
  // receiving class. If the method is not supported by the receiver
  // (as a static method or at all) then a NULL pointer is returned.
  // Overrides are not expected.

  somMethodPtr somFindSMethodOk(in somId methodId);
  // Uses <somFindSMethod>, and raises an error if the result is NULL.
  // Overrides are not expected.

  somMethodPtr somLookupMethod(in somId methodId);
  // Like <somFindSMethodOK>, but without restriction to static methods.
  // Overrides are not expected.


#ifdef SOMLEGACY1

  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.
  // Overrides are not expected.

  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.
  // Overrides are not expected.
#endif

  //########### [Testing] #############

  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.
  // Overrides are not expected.

  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.
  // Overrides are not expected.

  boolean somSupportsMethod(in somId mId);
  // Returns 1 (true) if the indicated method is supported by this
  // class and 0 (false) otherwise.
  // Overrides are not expected.

  somMethodPtr somDefinedMethod(in somMToken method);
  // If the receiving class explicitly defines an implementation for
  // the indicated method, then the address of a function that will invoke
  // this implementation is returned. Otherwise NULL is returned.
  // Overrides are not expected.

  SOMClass somMethodImplOwner(inout somMethodData md);
  // Returns the owner of the implementation of the method indicated by md
  // for instances of the receiving class, and loads md->method with a
  // pointer to the method implementation. If the receiving class doesn't
  // support the method, md->method is not changed, and null is returned.
  // Implementations that are automatically installed by SOM (such as for
  // SOMObject's initializers and for legacy support of somInit) are
  // reported as being owned by SOMObject.
  // Overrides are not expected.


//############## [Dynamic] #################

  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 pointer to a function that prints an
  // informative message and terminates execution 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,

#ifdef SOMLEGACY1
                somcPrivate1,
#else
                somcReserved1,
#endif
                                somClassReady,
                                somGetName,

#ifdef SOMLEGACY1
                somcPrivate2,
#else
                somcReserved2,
#endif
                                somDescendedFrom,
                                somCheckVersion,
                                somFindMethod,
                                somFindMethodOk,
                                somSupportsMethod,
                                somGetNumMethods,
                                somGetInstanceSize,
                somcPrivate3,
                                somGetInstancePartSize,
                                somGetMethodIndex,
                                somGetNumStaticMethods,
#ifdef SOMLEGACY1
                                somGetPClsMtab,
#else
                somcReserved3,
#endif
                                somGetClassMtab,
                                somAddStaticMethod,
                                somOverrideSMethod,
                                somAddDynamicMethod,
                                somcUnused1,
#ifdef SOMLEGACY1
                                somGetApplyStub,
#else
                somcReserved4,
#endif
                                somFindSMethod,
                                somFindSMethodOk,
                                somGetMethodDescriptor,
                                somGetNthMethodInfo,
                                somSetClassData,
                                somGetClassData,
                                somNewNoInit,
                                somRenewNoInit,
                                somGetInstanceToken,
                                somGetMemberToken,
                                somcUnused2, //# used to be somSetMethodDescriptor
                                somGetMethodData,
                                somOverrideMtab,
                                somGetMethodToken,
                                somGetParents,
                                somUnused3, //# used to be somGetPClsMtabs
                                somInitMIClass,
                                somGetVersionNumbers,
                                somLookupMethod,
                                _get_somInstanceDataOffsets,
                                somRenewNoZero,
                                somRenewNoInitNoZero,
                                somAllocate,
                                somDeallocate,
                                somGetRdStub,
                                somGetNthMethodData,

                somcPrivate8,
                somcPrivate9,
                                _get_somDirectInitClasses,
                somcPrivate10,
                somcPrivate11,
                somcPrivate12,
                somcPrivate13,
                somcPrivate14,
                                somMethodImplOwner, //# replaces earlier private method
                somcPrivate15,
                somcPrivate16,
                                somDefinedMethod,
                somcPrivate17,
                somcPrivate18,
                somcPrivate19,
                                somClassOfNewClassWithParents,
                somcPrivate20,
                                somcUnused5,
                                somcUnused6,
                                somcUnused7,
                                _get_somDataAlignment,
                somcPrivate21,
                                somcUnused8,
                somcPrivate22,
                                somcUnused9,
                                somcUnused10,
                                somGetMarshalPlan,
                                somcUnused11,
		somPrivate23,
				somJoin,
				somEndow;


    // Class Modifiers
    callstyle = oidl;
    majorversion = 1;
    minorversion = 6; // for som3.0 kernel
    filestem = somcls;
    dllname = "som.dll";

    // Attribute Modifiers
    somDataAlignment: nodata;
    somInstanceDataOffsets: nodata;
    somDirectInitClasses: nodata;
    somDirectAssignClasses: nodata;
    somClassAllocate: nodata, nonstaticaccessors;
    somClassDeallocate: nodata, nonstaticaccessors;

    //# Method Modifiers
    somClassReady: pcall;
    somInitMIClass: pcall;
    somClassAssert: nonstatic;
    somClassOfNewClassWithParents: procedure, noself;
    somMakeUserRdStub: nonstatic;
    somGetMethodProc: nonstatic;
    somAllocate: nonstatic;
    somDeallocate: nonstatic;
    somMethodImplOwner: nonstatic;
    somCloneClass: nonstatic;
    somCastObjCls: nonstatic;
    somResetObjCls: nonstatic;
    somSetUserPCallDispatch: nonstatic;
    somGetInstanceInitMask: nonstatic;
    somGetInstanceAssignMask: nonstatic;
    somGetInstanceDestructMask: nonstatic;
    somFindSMethod: nonstatic; // so can execute in SP
    somImportedClass: nonstatic;
    somLookupTerminal: nonstatic;
    _get_somInstanceDataOffsets: dual_owned_result;
    somGetName: dual_owned_result;
    somGetPClsMtab: dual_owned_result;


    };
#endif /* __SOMIDL__ */

};

#endif  /* somcls_idl */
