home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
som30tk.zip
/
som30os2.zip
/
include
/
somcls.idl
< prev
next >
Wrap
Text File
|
1996-12-24
|
25KB
|
597 lines
//# @(#) 1.53 src/somk/somcls.idl, somk.sc, som3.0 6/13/96 10:37:49 [12/24/96 07:40:21]
// 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 */