OS/2 Shareware BBS: 10 Tools/10-Tools.zip/tolkit45.zip/os2tk45/som/include/somcls.sc

Text File | 1999-02-22 | 23KB | 484 lines

/*
 * This file was generated by the SOM Compiler.
 * FileName: somcls.sc.
 * Generated using:
 *     SOM Precompiler somipc: 2.29.1.17
 *     SOM Emitter emitsc: 2.47
 */
#include <somobj.sc>

class: SOMClass,
    externalstem = sommc, majorversion = 1,
    minorversion = 5, filestem = somcls;

    --   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. Also, the
    --   restriction may be lifted in the future.
    --


parent class: SOMObject;


release order:
    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,
    somcPrivate1, somGetMethodData,
    somOverrideMtab, somGetMethodToken,
    somGetParents, somGetPClsMtabs,
    somInitMIClass, somGetVersionNumbers,
    somLookupMethod, _get_somInstanceDataOffsets,
    somRenewNoZero, somRenewNoInitNoZero,
    somAllocate, somDeallocate,
    somGetRdStub, somGetNthMethodData,
    somcPrivate2, somcPrivate3,
    _get_somDirectInitClasses, somcPrivate5,
    somcPrivate6, somcPrivate7,
    somcPrivate8, somcPrivate9,
    somcPrivate10, somcPrivate11,
    somcPrivate12, somDefinedMethod,
    somcPrivate13, somcPrivate14,
    somcPrivate15, somcPrivate16,
    somcPrivate17, somcPrivate18,
    somcPrivate19, somcPrivate20,
    _get_somDataAlignment, somcPrivate21,
    somcPrivate22, somcPrivate23,
    somcPrivate24, somcPrivate25;

methods:
group: somDataAlignment;

    long   _get_somDataAlignment(), attribute, descriptor = ::SOMClass::_get_somDataAlignment;

    --  The alignment required for the instance data structure
    --  introduced by the receiving class.

group: somInstanceDataOffsets, nodata, nonstatic;

    SOMClass_somOffsets   _get_somInstanceDataOffsets(), attribute, nodata,
    nonstatic, descriptor = ::SOMClass::_get_somInstanceDataOffsets;

    --  A sequence of the instance data offsets for all classes used in
    --  the derivation of the receiving class (including the receiver).

group: somDirectInitClasses, nonstatic;

    SOMClass_SOMClassSequence   _get_somDirectInitClasses(), attribute, nonstatic,
    descriptor = ::SOMClass::_get_somDirectInitClasses;

    --  The ancestors whose initializers the receiving
    --  class wants to directly invoke.

methods:


    SOMObject*   somNew(), descriptor = ::SOMClass::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(), descriptor = ::SOMClass::somNewNoInit;

    --  Equivalent to somNew except that somDefaultInit is not called.

    SOMObject*   somRenew(void* obj), descriptor = ::SOMClass::somRenew;

    --  Equivalent to somNew except that storage is not allocated.
    --  <obj> is taken as the address of the new object.

    SOMObject*   somRenewNoInit(void* obj), descriptor = ::SOMClass::somRenewNoInit;

    --  Equivalent to somRenew except that somDefaultInit is not called.

    SOMObject*   somRenewNoZero(void* obj), descriptor = ::SOMClass::somRenewNoZero;

    --  Equivalent to somRenew except that memory is not zeroed out.

    SOMObject*   somRenewNoInitNoZero(void* obj), descriptor = ::SOMClass::somRenewNoInitNoZero;

    --  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.

    somToken   somAllocate(long size), descriptor = ::SOMClass::somAllocate, nonstatic;

    --  Allocates memory to hold an object and returns a pointer to this memory.
    --  This is a nonstatic method, and cannot be overridden. The default
    --  implementation calls SOMMalloc, but a class designer can specify a
    --  different implementation using the somallocate modifier in IDL. The
    --  allocator takes the same parameters as this method.

    void   somDeallocate(somToken memptr), descriptor = ::SOMClass::somDeallocate, nonstatic;

    --  Zeros out the method table pointer stored in the word pointed to by
    --  memptr, and then deallocates the block of memory pointed to by memptr.
    --  This is a nonstatic method and cannot be overridden. The default
    --  deallocator called is SOMFree, but a class designer can specify a
    --  different deallocator using the somdeallocate modifier in IDL. The
    --  deallocator takes a char* (memptr) and a long (size) as arguments.

    void   somInitClass(string className,
        SOMClass* parentClass,
        long dataSize,
        long maxStaticMethods,
        long majorVersion,
        long minorVersion), descriptor = ::SOMClass::somInitClass;

    --  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(long inherit_vars,
        string className,
        SOMClass_SOMClassSequence* parentClasses,
        long dataSize,
        long dataAlignment,
        long maxStaticMethods,
        long majorVersion,
        long minorVersion), descriptor = ::SOMClass::somInitMIClass, caller_owns_parameters = className, parentClasses;

    --  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(somId methodId,
        somId methodDescriptor,
        somMethodPtr method,
        somMethodPtr redispatchStub,
        somMethodPtr applyStub), descriptor = ::SOMClass::somAddStaticMethod, caller_owns_parameters = methodId;

    --  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(somId methodId,
        somId methodDescriptor,
        somMethodPtr method,
        somMethodPtr applyStub), descriptor = ::SOMClass::somAddDynamicMethod, caller_owns_parameters = methodId;

    --  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 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
    --
    --  <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(somId methodId,
        somMethodPtr method), descriptor = ::SOMClass::somOverrideSMethod, caller_owns_parameters = methodId;

    --  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(), descriptor = ::SOMClass::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(somId methodId), descriptor = ::SOMClass::somGetApplyStub, caller_owns_parameters = 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(), descriptor = ::SOMClass::somGetClassData;

    void   somSetClassData(somClassDataStructure* cds), descriptor = ::SOMClass::somSetClassData;

    --  The class' pointer to the static <className>ClassData structure.

    somMethodTab*   somGetClassMtab(), descriptor = ::SOMClass::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(), descriptor = ::SOMClass::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(), descriptor = ::SOMClass::somGetInstancePartSize;

    --  The size in bytes of the instance data introduced by the receiving
    --  class.

    long   somGetInstanceSize(), descriptor = ::SOMClass::somGetInstanceSize;

    --  The total size of an instance of the receiving class.

    somDToken   somGetInstanceToken(), descriptor = ::SOMClass::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(long memberOffset,
        somDToken instanceToken), descriptor = ::SOMClass::somGetMemberToken, caller_owns_parameters = instanceToken,
    caller_owns_result;

    --  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(somId methodId,
        somMethodData* md), descriptor = ::SOMClass::somGetMethodData, caller_owns_parameters = methodId;

    --  If a method with id <methodId> is supported by the target class,
    --  the structure pointed to by <md> is loaded with method information
    --  and the value 1 is returned. In this case, if the method is not
    --  dynamic, md->method is loaded with the result of somClassResolve on
    --  the target class for the method. If the method is not supported,
    --  md->id is loaded with 0, and the value 0 is returned.

    somMethodProc*   somGetRdStub(somId methodId), descriptor = ::SOMClass::somGetRdStub, caller_owns_parameters = 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(somId methodId), descriptor = ::SOMClass::somGetMethodDescriptor, caller_owns_parameters = methodId;

    --  Returns the method descriptor for the indicated method.    If
    --  this object does not support the indicated method then NULL is
    --  returned.

    long   somGetMethodIndex(somId id), descriptor = ::SOMClass::somGetMethodIndex, caller_owns_parameters = 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(somId methodId), descriptor = ::SOMClass::somGetMethodToken, caller_owns_parameters = 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(), descriptor = ::SOMClass::somGetName;

    --  This object's class name as a NULL terminated string.

    boolean   somGetNthMethodData(long n,
        somMethodData* md), descriptor = ::SOMClass::somGetNthMethodData;

    --  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(long n,
        somId* descriptor), descriptor = ::SOMClass::somGetNthMethodInfo;

    --  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(), descriptor = ::SOMClass::somGetNumMethods;

    --  The number of methods currently supported by this class,
    --  including inherited methods (both static and dynamic).

    long   somGetNumStaticMethods(), descriptor = ::SOMClass::somGetNumStaticMethods;

    --  The number of static methods that this class has.  Can
    --  be used by a child class when initializing its method table.

    SOMClass*   somGetParent(), descriptor = ::SOMClass::somGetParent;

    --  Returns the parent class of self (along its "left-hand" derivation
    --  path), if one exists and NULL otherwise.

    SOMClass_SOMClassSequence   somGetParents(), descriptor = ::SOMClass::somGetParents, caller_owns_result;

    --  The parent classes of self.

    void   somGetVersionNumbers(long* majorVersion,
        long* minorVersion), descriptor = ::SOMClass::somGetVersionNumbers;

    --  Returns the class' major and minor version numbers in the corresponding
    --  output parameters.

    boolean   somFindMethod(somId methodId,
        somMethodPtr* m), descriptor = ::SOMClass::somFindMethod, caller_owns_parameters = methodId;

    --  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(somId methodId,
        somMethodPtr* m), descriptor = ::SOMClass::somFindMethodOk, caller_owns_parameters = methodId;

    --  Just like <somFindMethod> except that if the method is not
    --  supported then an error is raised and execution is halted.

    somMethodPtr   somFindSMethod(somId methodId), descriptor = ::SOMClass::somFindSMethod, caller_owns_parameters = 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(somId methodId), descriptor = ::SOMClass::somFindSMethodOk, caller_owns_parameters = methodId;

    --  Uses <somFindSMethod>, and raises an error if the result is NULL.

    somMethodPtr   somLookupMethod(somId methodId), descriptor = ::SOMClass::somLookupMethod, caller_owns_parameters = methodId;

    --  Like <somFindSMethodOK>, but without restriction to static methods.

    boolean   somCheckVersion(long majorVersion,
        long minorVersion), descriptor = ::SOMClass::somCheckVersion;

    --  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(SOMClass* aClassObj), descriptor = ::SOMClass::somDescendedFrom;

    --  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(somId mId), descriptor = ::SOMClass::somSupportsMethod, caller_owns_parameters = mId;

    --  Returns 1 (true) if the indicated method is supported by this
    --  class and 0 (false) otherwise.

    somMethodPtr   somDefinedMethod(somMToken method), descriptor = ::SOMClass::somDefinedMethod, caller_owns_parameters = method;

    --  if the receiving class either introduces or overrides the
    --  indicated method, then its somMethodPtr is returned, otherwise
    --  NULL is returned.

    void   somOverrideMtab(), descriptor = ::SOMClass::somOverrideMtab;

    --  Overrides the method table pointers to point to the redispatch stubs.
    --  All the methods except somDispatch methods are overriden.