home *** CD-ROM | disk | FTP | other *** search
/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / include / somapi.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-01-24  |  35.2 KB  |  876 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.         Last change:  KAS  25 Oct 94   12:55 pm
  13.  */
  14. /* %Z% %I% %W% %G% %U% [%H% %T%] */
  15.  
  16. /*
  17.  */
  18.  
  19. /*
  20.  *    SOMAPI.H
  21.  *
  22.  *    Note: the typedefs in this file explicitly show pointers
  23.  *    to objects that support an interface described by IDL. Thus, these are
  24.  *    not IDL typedefs; they are C/C++ typedefs that reflect the implementation
  25.  *    of object references in SOM as pointers to structures in memory.
  26.  */
  27.  
  28. #ifndef somapi_h
  29. #define somapi_h
  30.  
  31. #if !defined(_WIN32)
  32. /*  SOM Version Numbers  */
  33. SOMEXTERN long SOMDLINK SOM_MajorVersion;
  34. SOMEXTERN long SOMDLINK SOM_MinorVersion;
  35.  
  36. /*  SOM Thread Support  */
  37. SOMEXTERN long SOMDLINK SOM_MaxThreads;
  38. #else
  39. /*  SOM Version Numbers  */
  40. SOMEXTERN WIN32_DLLIMPORT long SOMDLINK SOM_MajorVersion;
  41. SOMEXTERN WIN32_DLLIMPORT long SOMDLINK SOM_MinorVersion;
  42.  
  43. /*  SOM Thread Support  */
  44. SOMEXTERN WIN32_DLLIMPORT long SOMDLINK SOM_MaxThreads;
  45. #endif
  46.  
  47. /*----------------------------------------------------------------------
  48.  *  Typedefs for pointers to functions
  49.  */
  50.  
  51. typedef void    SOMLINK somTD_classInitRoutine(SOMClass *, SOMClass *);
  52. typedef int     SOMLINK somTD_SOMOutCharRoutine(char);
  53. typedef int     SOMLINK somTD_SOMLoadModule(IN string /* className */,
  54.                                         IN string     /* fileName */,
  55.                                         IN string     /* functionName */,
  56.                                         IN long    /* majorVersion */,
  57.                                         IN long    /* minorVersion */,
  58.                                         OUT somToken * /* modHandle */);
  59. typedef int     SOMLINK somTD_SOMDeleteModule(IN somToken /* modHandle */);
  60. typedef string SOMLINK somTD_SOMClassInitFuncName(void);
  61. typedef somToken        SOMLINK somTD_SOMMalloc(IN size_t /* nbytes */);
  62. typedef somToken        SOMLINK somTD_SOMCalloc(IN size_t /* element_count */,
  63.                                         IN size_t /* element_size */);
  64. typedef somToken        SOMLINK somTD_SOMRealloc(IN somToken /* memory */,
  65.                                          IN size_t /* nbytes */);
  66. typedef void    SOMLINK somTD_SOMFree(IN somToken /* memory */);
  67. typedef void    SOMLINK somTD_SOMError(IN int      /* code */,
  68.                                        IN string  /* fileName */,
  69.                                        IN int      /* lineNum */);
  70. typedef unsigned long SOMLINK somTD_SOMCreateMutexSem (OUT somToken *sem);
  71. typedef unsigned long SOMLINK somTD_SOMRequestMutexSem (IN somToken sem);
  72. typedef unsigned long SOMLINK somTD_SOMReleaseMutexSem (IN somToken sem);
  73. typedef unsigned long SOMLINK somTD_SOMDestroyMutexSem (IN somToken sem);
  74. typedef unsigned long SOMLINK somTD_SOMGetThreadId (void);
  75.  
  76. /*----------------------------------------------------------------------
  77.  *  Windows extra procedures:
  78.  */
  79.  
  80. SOMEXTERN void SOMLINK somSetOutChar(somTD_SOMOutCharRoutine *outch);
  81. SOMEXTERN SOMClassMgr * SOMLINK somMainProgram (void);
  82. SOMEXTERN void SOMLINK somEnvironmentEnd (void);
  83. SOMEXTERN boolean SOMLINK somAbnormalEnd (void);
  84.  
  85. /*--------------------------------------------------------*/
  86.  
  87.  
  88. #ifndef SOM_MDT_DEFINED
  89. /* -- Method/Data Tokens -- For locating methods and data members. */
  90. typedef somToken somMToken;
  91. typedef somToken somDToken;
  92. #endif
  93.  
  94. /*----------------------------------------------------------------------
  95.  *  The Method Table Structure
  96.  */
  97.  
  98. #ifndef SOM_MTAB_DEFINED
  99. /* -- to specify an embedded object (or array of objects). */
  100. typedef struct {
  101.     SOMClass     **copp; /* address of class of object ptr */
  102.     long         cnt;    /* object count */
  103.     long         offset; /* Offset to pointer (to embedded objs) */
  104. } somEmbeddedObjStruct;
  105.  
  106. #ifndef SOM_CLASSINFO_DEFINED
  107. typedef somToken somClassInfo;
  108. #endif
  109.  
  110. typedef struct somMethodTabStruct {
  111.     SOMClass        *classObject;
  112.     somClassInfo    *classInfo;
  113.     char            *className;
  114.     long            instanceSize;
  115.     long            dataAlignment;
  116.     long            mtabSize;
  117.     long            protectedDataOffset; /* from class's introduced data */
  118.     somDToken       protectedDataToken;
  119.     somEmbeddedObjStruct *embeddedObjs;
  120.     /* remaining structure is opaque */
  121.     somMethodProc* entries[1];
  122. } somMethodTab, *somMethodTabPtr;
  123. #endif
  124.  
  125.  
  126. /* -- For building lists of method tables */
  127. typedef
  128.     struct somMethodTabList {
  129.         somMethodTab             *mtab;
  130.         struct somMethodTabList  *next;
  131.     } somMethodTabList, *somMethodTabs;
  132.  
  133.  
  134. /* -- For building lists of class objects */
  135. typedef
  136.     struct somClassList {
  137.         SOMClass   *cls;
  138.         struct somClassList *next;
  139.     } somClassList, *somClasses;
  140.  
  141. /* -- For building lists of objects */
  142. typedef struct somObjectList {
  143.     SOMObject   *obj;
  144.     struct somObjectList *next;
  145. } somObjectList, *somObjects;
  146.  
  147. /*---------------------------------------------------------------------
  148.  * C++-style constructors are called initializers in SOM. Initializers
  149.  * are methods that receive a pointer to a somCtrlStruct as an argument.
  150.  */
  151.  
  152. typedef  struct  {
  153.     SOMClass      *cls;  /* the class whose introduced data is to be initialized */
  154.     somMethodProc *defaultInit;
  155.     somMethodProc *defaultCopyInit;
  156.     somMethodProc *defaultConstCopyInit;
  157.     somMethodProc *defaultNCArgCopyInit;
  158.     long          dataOffset;
  159.     somMethodProc *legacyInit;
  160. } somInitInfo;
  161.  
  162. typedef struct {
  163.     SOMClass      *cls;  /* the class whose introduced data is to be destroyed */
  164.     somMethodProc *defaultDestruct;
  165.     long          dataOffset;
  166.     somMethodProc *legacyUninit;
  167. } somDestructInfo;
  168.  
  169. typedef struct {
  170.     SOMClass      *cls;  /* the class whose introduced data is to be assigned */
  171.     somMethodProc *defaultAssign;
  172.     somMethodProc *defaultConstAssign;
  173.     somMethodProc *defaultNCArgAssign;
  174.     somMethodProc *udaAssign;
  175.     somMethodProc *udaConstAssign;
  176.     long          dataOffset;
  177. } somAssignInfo;
  178.  
  179. typedef octet *somBooleanVector;
  180. #ifndef SOM_CTI_DEFINED
  181. typedef somToken somCtrlInfo;
  182. #endif
  183.  
  184. typedef struct somInitCtrlStruct {
  185.     somBooleanVector mask; /* an array of booleans to control ancestor calls */
  186.     somInitInfo     *info; /* an array of structs */
  187.     int              infoSize; /* increment for info access */
  188.     somCtrlInfo      ctrlInfo;
  189. } somInitCtrl;
  190.  
  191. typedef struct somDestructCtrlStruct {
  192.     somBooleanVector  mask; /* an array of booleans to control ancestor calls */
  193.     somDestructInfo  *info; /* an array of structs */
  194.     int               infoSize; /* increment for info access */
  195.     somCtrlInfo       ctrlInfo;
  196. } somDestructCtrl;
  197.  
  198. typedef struct somAssignCtrlStruct {
  199.     somBooleanVector  mask; /* an array of booleans to control ancestor calls */
  200.     somAssignInfo    *info; /* an array of structs */
  201.     int               infoSize; /* increment for info access */
  202.     somCtrlInfo       ctrlInfo;
  203. } somAssignCtrl;
  204.  
  205.  
  206.  
  207.  
  208. /*----------------------------------------------------------------------
  209.  *  The Class Data Structures -- these are used to implement static
  210.  *  method and data interfaces to SOM objects.
  211.  */
  212.  
  213. /* -- (Generic) Class data Structure */
  214. typedef struct {
  215.     SOMClass *classObject; /* changed by shadowing */
  216.     somToken tokens[1];    /* method tokens, etc. */
  217. } somClassDataStructure, *somClassDataStructurePtr;
  218.  
  219. /*
  220.  * A special info access structure pointed to by
  221.  * the parentMtab entry of somCClassDataStructure.
  222.  */
  223. #if !defined(_WIN32)
  224. typedef void somTP_somRenewNoInitNoZeroThunk(void*);
  225. #else
  226. typedef void SOMLINK somTP_somRenewNoInitNoZeroThunk(void*);
  227. #endif /*_WIN32*/
  228.  
  229.  
  230. typedef somTP_somRenewNoInitNoZeroThunk *somTD_somRenewNoInitNoZeroThunk;
  231.  
  232. typedef struct {
  233.     somMethodTab    *mtab; /* this class' mtab -- changed by shadowing */
  234.     somMethodTabs   next; /* the parent mtabs -- unchanged by shadowing */
  235.     SOMClass        *classObject; /* unchanged by shadowing */
  236.     somTD_somRenewNoInitNoZeroThunk somRenewNoInitNoZeroThunk; /* changed by shadowing */
  237.     long            instanceSize; /* changed by shadowing */
  238.     somMethodProc   **initializers; /* resolved initializer array in releaseorder */
  239.     somMethodProc   **resolvedMTokens;  /* resolved methods */
  240.     somInitCtrl     initCtrl; /* these fields are filled in if somDTSClass&2 is on */
  241.     somDestructCtrl destructCtrl;
  242.     somAssignCtrl   assignCtrl;
  243.     long            embeddedTotalCount;
  244.     long            hierarchyTotalCount;
  245.     long            unused;
  246. } somParentMtabStruct, *somParentMtabStructPtr;
  247.  
  248. /*
  249.  * (Generic) Auxiliary Class Data Structure
  250.  */
  251. typedef struct {
  252.     somParentMtabStructPtr parentMtab;
  253.     somDToken              instanceDataToken;
  254.     somMethodProc          *wrappers[1]; /* for valist methods */
  255. } somCClassDataStructure, *somCClassDataStructurePtr;
  256.  
  257.  
  258. /*---------------------------------------------------------------------
  259.  *  Offset-based method resolution.
  260.  */
  261.  
  262. SOMEXTERN somMethodProc * SOMLINK somResolve(SOMObject *obj, somMToken mdata);
  263. SOMEXTERN somMethodProc * SOMLINK somParentResolve(somMethodTabs parentMtabs,
  264.                                          somMToken mToken);
  265. SOMEXTERN somMethodProc * SOMLINK somParentNumResolve(somMethodTabs parentMtabs,
  266.                                          int parentNum,
  267.                                          somMToken mToken);
  268. SOMEXTERN somMethodProc * SOMLINK somClassResolve(SOMClass *, somMToken mdata);
  269. SOMEXTERN somMethodProc * SOMLINK somAncestorResolve(SOMObject *obj, /* the object */
  270.                                            somCClassDataStructure *ccds, /* id the ancestor */
  271.                                            somMToken mToken);
  272. SOMEXTERN somMethodProc * SOMLINK somResolveByName(SOMObject *obj,
  273.                                                    char *methodName);
  274. /*------------------------------------------------------------------------------
  275.  * Offset-based data resolution
  276.  */
  277. SOMEXTERN somToken SOMLINK somDataResolve(SOMObject *obj, somDToken dataId);
  278. SOMEXTERN somToken SOMLINK somDataResolveChk(SOMObject *obj, somDToken dataId);
  279.  
  280.  
  281. /*----------------------------------------------------------------------
  282.  *  Misc. procedures:
  283.  */
  284.  
  285. /*
  286.  *  Create and initialize the SOM environment
  287.  *
  288.  *  Can be called repeatedly
  289.  *
  290.  *  Will be called automatically when first object (including a class
  291.  *  object) is created, if it has not already been done.
  292.  *
  293.  *  Returns the SOMClassMgrObject
  294.  */
  295. SOMEXTERN SOMClassMgr * SOMLINK somEnvironmentNew (void);
  296.  
  297.  
  298. /*
  299.  * Test whether <obj> is a valid SOM object. This test is based solely on
  300.  * the fact that (on this architecture) the first word of a SOM object is a
  301.  * pointer to its method table. The test is therefore most correctly understood
  302.  * as returning true if and only if <obj> is a pointer to a pointer to a
  303.  * valid SOM method table. If so, then methods can be invoked on <obj>.
  304.  */
  305. SOMEXTERN boolean SOMLINK somIsObj(somToken obj);
  306.  
  307. /*
  308.  * Return the class that introduced the method represented by a given method token.
  309.  */
  310. SOMEXTERN SOMClass* SOMLINK somGetClassFromMToken(somMToken mToken);
  311.  
  312.  
  313. /*----------------------------------------------------------------------
  314.  *  String Manager: stem <somsm>
  315.  */
  316. SOMEXTERN somId SOMLINK somCheckId (somId id);
  317. /* makes sure that the id is registered and in normal form, returns */
  318. /* the id */
  319.  
  320. SOMEXTERN int SOMLINK somRegisterId(somId id);
  321. /* Same as somCheckId except returns 1 (true) if this is the first */
  322. /* time the string associated with this id has been registered, */
  323. /* returns 0 (false) otherwise */
  324.  
  325. SOMEXTERN somId SOMLINK somIdFromString (string aString);
  326.  
  327. SOMEXTERN string SOMLINK somStringFromId (somId id);
  328.  
  329. SOMEXTERN int SOMLINK somCompareIds(somId id1, somId id2);
  330. /* returns true (1) if the two ids are equal, else false (0) */
  331.  
  332. SOMEXTERN unsigned long SOMLINK somTotalRegIds(void);
  333. /* Returns the total number of ids that have been registered so far, */
  334. /* you can use this to advise the SOM runtime concerning expected */
  335. /* number of ids in later executions of your program, via a call to */
  336. /* somSetExpectedIds defined below */
  337.  
  338. SOMEXTERN void SOMLINK somSetExpectedIds(unsigned long numIds);
  339. /* Tells the SOM runtime how many unique ids you expect to use during */
  340. /* the execution of your program, this can improve space and time */
  341. /* utilization slightly, this routine must be called before the SOM */
  342. /* environment is created to have any effect */
  343.  
  344. SOMEXTERN unsigned long SOMLINK somUniqueKey(somId id);
  345. /* Returns the unique key for this id, this key will be the same as the */
  346. /* key in another id if and only if the other id refers to the same */
  347. /* name as this one */
  348.  
  349. SOMEXTERN void SOMLINK somBeginPersistentIds(void);
  350. /* Tells the id manager that strings for any new ids that are */
  351. /* registered will never be freed or otherwise modified. This allows */
  352. /* the id manager to just use a pointer to the string in the */
  353. /* unregistered id as the master copy of the ids string. Thus saving */
  354. /* space */
  355. /* Under normal use (where ids are static varibles) the string */
  356. /* associated with an id would only be freed if the code module in */
  357. /* which it occured was unloaded */
  358.  
  359. SOMEXTERN void SOMLINK somEndPersistentIds(void);
  360. /* Tells the id manager that strings for any new ids that are */
  361. /* registered may be freed or otherwise modified.  Therefore the id */
  362. /* manager must copy the strings inorder to remember the name of an */
  363. /* id. */
  364.  
  365. /*----------------------------------------------------------------------
  366.  *  Class Manager: SOMClassMgr, stem <somcm>
  367.  */
  368.  
  369. /*Global class manager object */
  370. #if !defined(_WIN32)
  371. SOMEXTERN SOMClassMgr * SOMDLINK SOMClassMgrObject;
  372. #else
  373. SOMEXTERN WIN32_DLLIMPORT SOMClassMgr * SOMDLINK SOMClassMgrObject;
  374. #endif
  375.  
  376. /* The somRegisterClassLibrary function is provided for use
  377.  * in SOM class libraries on platforms that have loader-invoked
  378.  * entry points associated with shared libraries (DLLs).
  379.  *
  380.  * This function registers a SOM Class Library with the SOM Kernel.
  381.  * The library is identified by its file name and a pointer
  382.  * to its initialization routine.  Since this call may occur
  383.  * prior to the invocation of somEnvironmentNew, its actions
  384.  * are deferred until the SOM environment has been initialized.
  385.  * At that time, the SOMClassMgrObject is informed of all
  386.  * pending library initializations via the _somRegisterClassLibrary
  387.  * method.  The actual invocation of the library's initialization
  388.  * routine will occur during the execution of the SOM_MainProgram
  389.  * macro (for statically linked libraries), or during the _somFindClass
  390.  * method (for libraries that are dynamically loaded).
  391.  */
  392. SOMEXTERN void SOMLINK somRegisterClassLibrary (string libraryName,
  393.     somMethodProc *libraryInitRtn);
  394.  
  395. /*----------------------------------------------------------------------
  396.  * Method Stubs -- Signature Support
  397.  *
  398.  *
  399.  * This section defines the structures used to pass method signature
  400.  * ingo to the runtime. This supports selection of generic apply stubs
  401.  * and runtime generation of redispatchstubs when these are needed. The
  402.  * information is registered with the runtime when methods are defined.
  403.  *
  404.  * When calling somAddStaticMethod, if the redispatchStub is -1, then a
  405.  * pointer to a struct of type somApRdInfo is passed as the applyStub.
  406.  * Otherwise, the passed redispatchstub and applystub are taken as given.
  407.  * When calling somAddDynamicMethod, an actual apply stub must be passed.
  408.  * Redispatch stubs for dynamic methods are not available, nor is
  409.  * automated support for dynamic method apply stubs. The following
  410.  * atructures only appropriate in relation to static methods.
  411.  *
  412.  * In SOMr2, somAddStaticMethod can be called with an actual redispatchstub
  413.  * and applystub *ONLY* if the method doesn't return a structure. Recall
  414.  * that no SOMr1 methods returned structures, so SOMr1 binaries obey this
  415.  * restriction. The reason for this rule is that SOMr2 *may* use thunks,
  416.  * and thunks need to know if a structure is returned. We therefore assume
  417.  * that if no signature information is provided for a method through the
  418.  * somAddStaticMethod interface, then the method returns a scalar.
  419.  *
  420.  * If a structure is returned, then a -1 *must* be passed to
  421.  * somAddStaticMethod as a redispatchstub. In any case, if a -1 is passed,
  422.  * then this means that the applystub actually points to a structure of type
  423.  * somApRdInfo. This structure is used to hold and access signature
  424.  * information encoded as follows.
  425.  *
  426.  * If the somApRdInfo pointer is NULL, then, if the runtime was built with
  427.  * SOM_METHOD_STUBS defined, a default signature is assumed (no arguments,
  428.  * and no structure returned); otherwise, the stubs are taken as
  429.  * somDefaultMethod (which produces a runtime error when used) if dynamic
  430.  * stubs are not available.
  431.  *
  432.  * If the somApRdInfo pointer is not NULL, then the structure it points to can
  433.  * either include (non-null) redispatch and applystubs (the method is then
  434.  * assumed to return a structure), or null stubs followed by information needed
  435.  * to generate necessary stubs dynamically.
  436.  */
  437.  
  438. typedef unsigned long somRdAppType; /* method signature code -- see def below */
  439. typedef unsigned long somFloatMap[13]; /* float map -- see def below */
  440. typedef struct somMethodInfoStruct {
  441.     somRdAppType       callType;
  442.     long               va_listSize;
  443.     somFloatMap        *float_map;
  444. } somMethodInfo;
  445.  
  446. typedef struct somApRdInfoStruct {
  447.     somMethodProc *rdStub;
  448.     somMethodProc *apStub;
  449.     somMethodInfo *stubInfo;
  450. } somApRdInfo;
  451.  
  452. /*
  453.  * Values for somRdAppType are generated by summing one from column A and one
  454.  * from column B of the following constants:
  455.  */
  456. /* Column A: return type */
  457. #define SOMRdRetsimple     0 /* Return type is a non-float fullword */
  458. #define SOMRdRetfloat      2 /* Return type is (single) float */
  459. #define SOMRdRetdouble     4 /* Return type is double */
  460. #define SOMRdRetlongdouble 6 /* Return type is long double */
  461. #define SOMRdRetaggregate  8 /* Return type is struct or union */
  462. #define SOMRdRetbyte      10 /* Return type is a byte */
  463. #define SOMRdRethalf      12 /* Return type is a (2 byte) halfword */
  464. #define SOMRdRetsmallaggregate  14 /* Return type is a small struct or union */
  465. /* Column B: are there any floating point scalar arguments? */
  466. #define SOMRdNoFloatArgs   0
  467. #define SOMRdFloatArgs     1
  468.  
  469. /* A somFloatMap is only needed on RS/6000 */
  470. /*
  471.  * This is an array of offsets for up to the first 13 floating point arguments.
  472.  * If there are fewer than 13 floating point arguments, then there will be
  473.  * zero entries following the non-zero entries which represent the float args.
  474.  * A non-zero entry signals either a single- or a double-precision floating point
  475.  * argument. For a double-precision argument, the entry is the stack
  476.  * frame offset. For a single-precision argument the entry is the stack
  477.  * frame offset + 1. For the final floating point argument, add 2 to the
  478.  * code that would otherwise be used.
  479.  */
  480. #define SOMFMSingle 1        /* add to indicate single-precision */
  481. #define SOMFMLast   2        /* add to indicate last floating point arg */
  482.  
  483.  
  484. /*----------------------------------------------------------------------
  485.  * -- somApply --
  486.  *
  487.  * This routine replaces direct use of applyStubs in SOMr1. The reason
  488.  * for the replacement is that the SOMr1 style of applyStub is not
  489.  * generally available in SOMr2, which uses a fixed set of applyStubs,
  490.  * according to method information in the somMethodData. In particular,
  491.  * neither the redispatch stub nor the apply stub found in the method
  492.  * data structure are necessarily useful as such. The method somGetRdStub
  493.  * is the way to get a redispatch stub, and the above function is the
  494.  * way to call an apply stub. If an appropriate apply stub for the
  495.  * method indicated by md is available, then this is invoked and TRUE is
  496.  * returned; otherwise FALSE is returned.
  497.  *
  498.  * The va_list passed to somApply *must* include the target object,
  499.  * somSelf, as its first entry, and any single precision floating point
  500.  * arguments being passed to the the method procedure must be
  501.  * represented on the va_list using double precision values. retVal cannot
  502.  * be NULL.
  503.  */
  504.  
  505. #ifndef SOM_SMD_DEFINED
  506. typedef somToken somSharedMethodData;
  507. #endif
  508.  
  509. typedef struct somMethodDataStruct {
  510.     somId id;
  511.     long type;          /* 0=static, 1=dynamic 2=nonstatic */
  512.     somId descriptor;        /* for use with IR interfaces */
  513.     somMToken mToken;        /* NULL for dynamic methods */
  514.     somMethodPtr method;     /* depends on resolution context */
  515.     somSharedMethodData *shared;
  516. } somMethodData, *somMethodDataPtr;
  517.  
  518.  
  519. SOMEXTERN boolean SOMLINK somApply(SOMObject *somSelf,
  520.                                 somToken *retVal,
  521.                                 somMethodDataPtr mdPtr,
  522.                                 va_list ap);
  523.  
  524. /*---------------------------------------------------------------------
  525.  * -- somBuildClass --
  526.  *
  527.  * This procedure automates construction of a new class object. A variety of
  528.  * special structures are used to allow language bindings to statically define
  529.  * the information necessary to specify a class. Pointers to these static
  530.  * structures are accumulated into an overall "static class information"
  531.  * structure or SCI, passed to somBuildClass. The SCI has evolved over time.
  532.  * The current version is defined here.
  533.  */
  534.  
  535. #define SOM_SCILEVEL 4
  536.  
  537.  
  538. /* The SCI includes the following information:
  539.  *
  540.  * The address of a class's ClassData structure is passed.
  541.  * This structure should have the external name,
  542.  * <className>ClassData. The classObject field should be NULL
  543.  * (if it is not NULL, then a new class will not be built). somBuildClass will
  544.  * set this field to the address of the new class object when it is built.
  545.  *
  546.  * The address of the class's auxiliary ClassData structure is passed.
  547.  * Thi structure should have the external name,
  548.  * <className>CClassData. The parentMtab field will be set by somBuildClass.
  549.  * This field often allows method calls to a class object to be avoided.
  550.  *
  551.  * The other structures referenced by the static class information (SCI)
  552.  * are used to:
  553.  */
  554.  
  555. /*
  556.  * to specify a static method. The methodId used here must be
  557.  * a simple name (i.e., no colons). In all other cases,
  558.  * where a somId is used to identify a registered method,
  559.  * the somId can include explicit scoping. An explicitly-scoped
  560.  * method name is called a method descriptor. For example,
  561.  * the method introduced by SOMObject as somGetClass has the
  562.  * method descriptor "SOMObject::somGetClass". When a
  563.  * class is contained in an IDL module, the descriptor syntax
  564.  * <moduleName>::<className>::<methodName> can be used. Method
  565.  * descriptors can be useful when a class supports different methods
  566.  * that have the same name (note: IDL prevents this from occuring
  567.  * statically, but SOM itself has no problems with this).
  568.  */
  569. typedef struct somStaticMethodStruct {
  570.     somMToken *classData;
  571.     somId *methodId; /* this must be a simple name (no colons) */
  572.     somId *methodDescriptor;
  573.     somMethodProc *method;
  574.     somMethodProc *redispatchStub;
  575.     somMethodProc *applyStub;
  576. } somStaticMethod_t;
  577.  
  578. /* to specify an overridden method */
  579. typedef struct somOverideMethodStruct {
  580.     somId *methodId; /* this can be a method descriptor */
  581.     somMethodProc *method;
  582. } somOverrideMethod_t;
  583.  
  584. /* to inherit a specific parent's method implementation */
  585. typedef struct somInheritedMethodStruct {
  586.     somId     *methodId;  /* identify the method */
  587.     long parentNum;       /* identify the parent */
  588.     somMToken *mToken;    /* for parentNumresolve */
  589. } somInheritedMethod_t;
  590.  
  591. /* to register a method that has been moved from this */
  592. /* class <cls> upwards in the class hierachy to class <dest> */
  593. typedef struct somMigratedMethodStruct {
  594.     somMToken *clsMToken; /* points into the <cls> classdata structure */
  595.                           /* the method token in <dest> will copied here */
  596.     somMToken *destMToken;/* points into the <dest> classdata structure */
  597.                           /* the method token here will be copied to <cls> */
  598. } somMigratedMethod_t;
  599.  
  600. /* to specify non-internal data */
  601. typedef struct somNonInternalDataStruct {
  602.     somDToken *classData;
  603.     char *basisForDataOffset;
  604. } somNonInternalData_t;
  605.  
  606. /* to specify a "procedure" or "classdata" */
  607. typedef struct somProcMethodsStruct {
  608.     somMethodProc **classData, *pEntry;
  609. } somProcMethods_t;
  610.  
  611. /* to specify a general method "action" using somMethodStruct */
  612. /*
  613.   the type of action is specified by loading the type field of the
  614.   somMethodStruct. There are three bit fields in the overall type:
  615.  
  616.   action (in type & 0xFF)
  617.    0: static -- (i.e., virtual) uses somAddStaticMethod
  618.    1: dynamic -- uses somAddDynamicMethod (classData==0)
  619.    2: nonstatic -- (i.e., nonvirtual) uses somAddMethod
  620.    3: udaAssign -- registers a method as the udaAssign (but doesn't add the method)
  621.    4: udaConstAssign -- like 3, this doesn't add the method
  622.    5: somClassResolve Override (using the class pointed to by *classData)
  623.    6: somMToken Override (using the method token pointed to by methodId)
  624.                          (note: classData==0 for this)
  625.    7: classAllocate -- indicates the default heap allocator for this class.
  626.                        If classData == 0, then method is the code address (or NULL)
  627.                        If classData != 0, then *classData is the code address.
  628.                        No other info required (or used)
  629.    8: classDeallocate -- like 7, but indicates the default heap deallocator.
  630.    9: classAllocator -- indicates a non default heap allocator for this class.
  631.                         like 7, but a methodDescriptor can be given.
  632.  
  633.    === the following is not currently supported ===
  634.    binary data access -- in (type & 0x100), valid for actions 0,1,2,5,6
  635.    0: the method procedure doesn't want binary data access
  636.    1: the method procedure does want binary data access
  637.  
  638.    aggregate return -- in (type & 0x200), used when binary data access requested
  639.    0: method procedure doesn't return a structure
  640.    1: method procedure does return a structure
  641. */
  642.  
  643. typedef struct somMethodStruct {
  644.     unsigned long type;
  645.     somMToken *classData;
  646.     somId *methodId;
  647.     somId *methodDescriptor;
  648.     somMethodProc *method;
  649.     somMethodProc *redispatchStub;
  650.     somMethodProc *applyStub;
  651. } somMethods_t;
  652.  
  653. /* to specify a varargs function */
  654. typedef struct somVarargsFuncsStruct {
  655.     somMethodProc **classData, *vEntry;
  656. } somVarargsFuncs_t;
  657.  
  658. /* to specify dynamically computed information (incl. embbeded objs) */
  659. typedef struct {
  660.     int   version;              /* 1 for now */
  661.     long    instanceDataSize;   /* true size (incl. embedded objs) */
  662.     long    dataAlignment;      /* true alignment */
  663.     somEmbeddedObjStruct *embeddedObjs; /* array end == null copp */
  664. } somDynamicSCI;
  665.  
  666.  
  667. /*
  668.    to specify a DTS class, use the somDTSClass entry in the following
  669.    data structure. This entry is a bit vector interpreted as follows:
  670.  
  671.    (somDTSClass & 0x0001) == the class is a DTS C++ class
  672.    (somDTSClass & 0x0002) == the class wants the initCtrl entries
  673.                              of the somParentMtabStruct filled in.
  674.  
  675. */
  676.  
  677.  
  678.  
  679. /*
  680.  *  The Static Class Info Structure passed to somBuildClass
  681.  */
  682.  
  683. typedef struct somStaticClassInfoStruct {
  684.     unsigned long layoutVersion;  /* this struct defines layout version SOM_SCILEVEL */
  685.     unsigned long numStaticMethods;   /* count of smt entries */
  686.     unsigned long numStaticOverrides; /* count of omt entries */
  687.     unsigned long numNonInternalData; /* count of nit entries */
  688.     unsigned long numProcMethods;     /* count of pmt entries */
  689.     unsigned long numVarargsFuncs;    /* count of vft entries */
  690.     unsigned long majorVersion;
  691.     unsigned long minorVersion;
  692.     unsigned long instanceDataSize;   /* instance data introduced by this class */
  693.     unsigned long maxMethods;         /* count numStaticMethods and numMethods */
  694.     unsigned long numParents;
  695.     somId    classId;
  696.     somId    explicitMetaId;
  697.     long implicitParentMeta;
  698.     somId                  *parents;
  699.     somClassDataStructure  *cds;
  700.     somCClassDataStructure *ccds;
  701.     somStaticMethod_t      *smt; /* basic "static" methods for mtab */
  702.     somOverrideMethod_t    *omt; /* overrides for mtab */
  703.     char                   *nitReferenceBase;
  704.     somNonInternalData_t   *nit; /* datatokens for instance data */
  705.     somProcMethods_t       *pmt; /* Arbitrary ClassData members */
  706.     somVarargsFuncs_t      *vft; /* varargs stubs */
  707.     somTP_somClassInitFunc *cif; /* class init function */
  708.     /* end of layout version 1 */
  709.  
  710.     /* begin layout version 2 extensions */
  711.     long dataAlignment; /* the desired byte alignment for instance data */
  712.     /* end of layout version 2 */
  713.  
  714. #define SOMSCIVERSION 1
  715.  
  716.     /* begin layout version 3 extensions */
  717.     long numDirectInitClasses;
  718.     somId *directInitClasses;
  719.     unsigned long numMethods; /* general (including nonstatic) methods for mtab */
  720.     somMethods_t       *mt;
  721.     unsigned long protectedDataOffset; /* access = resolve(instanceDataToken) + offset */
  722.     unsigned long somSCIVersion;  /* used during development. currently = 1 */
  723.     unsigned long numInheritedMethods;
  724.     somInheritedMethod_t *imt; /* inherited method implementations */
  725.     unsigned long numClassDataEntries; /* should always be filled in */
  726.     somId *classDataEntryNames; /* either NULL or ptr to an array of somIds */
  727.     unsigned long numMigratedMethods;
  728.     somMigratedMethod_t *mmt; /* migrated method implementations */
  729.     unsigned long numInitializers; /* the initializers for this class */
  730.     somId *initializers;     /* in order of release */
  731.     unsigned long somDTSClass; /* used to identify a DirectToSOM class */
  732.     somDynamicSCI *dsci;  /* used to register dynamically computed info */
  733.     /* end of layout version 3 */
  734.  
  735. } somStaticClassInfo, *somStaticClassInfoPtr;
  736.  
  737. SOMEXTERN SOMClass * SOMLINK somBuildClass (
  738.                     long inherit_vars,
  739.                     somStaticClassInfo *sci,
  740.                     long majorVersion,
  741.                     long minorVersion);
  742.  
  743.   /*
  744.   The arguments to somBuildClass are as follows:
  745.  
  746.    inherit_vars: a bit mask used to control inheritance of implementation
  747.    Implementation is inherited from parent i iff the bit 1<<i is on, or i>=32.
  748.  
  749.    sci: the somStaticClassInfo defined above.
  750.  
  751.    majorVersion, minorVersion: the version of the class implementation.
  752.  
  753.    */
  754.  
  755.  
  756. /*---------------------------------------------------------------------
  757.  *  Used by old single-inheritance emitters to make class creation
  758.  *  an atomic operation. Kept for backwards compatability.
  759.  */
  760. SOMEXTERN void SOMLINK somConstructClass (
  761.                     somTD_classInitRoutine *classInitRoutine,
  762.                     SOMClass *parentClass,
  763.                     SOMClass *metaClass,
  764.                     somClassDataStructure *cds);
  765.  
  766.  
  767. /*
  768.  * Uses <SOMOutCharRoutine> to output its arguments under control of the ANSI C
  769.  * style format.  Returns the number of characters output.
  770.  */
  771. SOMEXTERN int SOMLINK somPrintf (string fmt, ...);
  772. /*
  773.  * vprint form of somPrintf
  774.  */
  775. SOMEXTERN int SOMLINK somVprintf (string fmt, va_list ap);
  776. /*
  777.  * Outputs (via somPrintf) blanks to prefix a line at the indicated level
  778.  */
  779. SOMEXTERN void SOMLINK somPrefixLevel (long level);
  780. /*
  781.  * Combines somPrefixLevel and somPrintf
  782.  */
  783. SOMEXTERN int SOMLINK somLPrintf (int level, string fmt, ...);
  784.  
  785. /*
  786.  *  Replaceable character output handler.
  787.  *  Points to the character output routine to be used in development
  788.  *  support.  Initialized to <somOutChar>, but may be reset at anytime.
  789.  *  Should return 0 (false) if an error occurs and 1 (true) otherwise.
  790.  */
  791.  
  792. SOMEXTERN somTD_SOMOutCharRoutine * SOMDLINK SOMOutCharRoutine;
  793.  
  794. /*----------------------------------------------------------------------
  795.  * Pointers to routines used to do dynamic code loading and deleting
  796.  */
  797.  
  798. SOMEXTERN somTD_SOMLoadModule * SOMDLINK SOMLoadModule;
  799. SOMEXTERN somTD_SOMDeleteModule * SOMDLINK SOMDeleteModule;
  800. SOMEXTERN somTD_SOMClassInitFuncName * SOMDLINK SOMClassInitFuncName;
  801.  
  802. /*----------------------------------------------------------------------
  803.  *  Replaceable SOM Memory Management Interface
  804.  *
  805.  *  External procedure variables SOMCalloc, SOMFree, SOMMalloc, SOMRealloc
  806.  *  have the same interface as their standard C-library analogs.
  807.  */
  808.  
  809. #if !defined(_WIN32)
  810. SOMEXTERN somTD_SOMCalloc  * SOMDLINK SOMCalloc;
  811. SOMEXTERN somTD_SOMFree    * SOMDLINK SOMFree;
  812. SOMEXTERN somTD_SOMMalloc  * SOMDLINK SOMMalloc;
  813. SOMEXTERN somTD_SOMRealloc * SOMDLINK SOMRealloc;
  814. #else
  815. SOMEXTERN WIN32_DLLIMPORT somTD_SOMCalloc  * SOMDLINK SOMCalloc;
  816. SOMEXTERN WIN32_DLLIMPORT somTD_SOMFree    * SOMDLINK SOMFree;
  817. SOMEXTERN WIN32_DLLIMPORT somTD_SOMMalloc  * SOMDLINK SOMMalloc;
  818. SOMEXTERN WIN32_DLLIMPORT somTD_SOMRealloc * SOMDLINK SOMRealloc;
  819. #endif
  820.  
  821. /*----------------------------------------------------------------------
  822.  *  Replaceable SOM Error handler
  823.  */
  824.  
  825. #if !defined(_WIN32)
  826. SOMEXTERN somTD_SOMError * SOMDLINK SOMError;
  827. #else
  828. SOMEXTERN WIN32_DLLIMPORT somTD_SOMError * SOMDLINK SOMError;
  829. #endif
  830.  
  831. /*----------------------------------------------------------------------
  832.  *  Replaceable SOM Semaphore Operations
  833.  *
  834.  *  These operations are used by the SOM Kernel to make thread-safe
  835.  *  state changes to internal resources.
  836.  */
  837. #if !defined(_WIN32)
  838. SOMEXTERN somTD_SOMCreateMutexSem  * SOMDLINK SOMCreateMutexSem;
  839. SOMEXTERN somTD_SOMRequestMutexSem * SOMDLINK SOMRequestMutexSem;
  840. SOMEXTERN somTD_SOMReleaseMutexSem * SOMDLINK SOMReleaseMutexSem;
  841. SOMEXTERN somTD_SOMDestroyMutexSem * SOMDLINK SOMDestroyMutexSem;
  842. #else
  843. SOMEXTERN WIN32_DLLIMPORT somTD_SOMCreateMutexSem  * SOMDLINK SOMCreateMutexSem;
  844. SOMEXTERN WIN32_DLLIMPORT somTD_SOMRequestMutexSem * SOMDLINK SOMRequestMutexSem;
  845. SOMEXTERN WIN32_DLLIMPORT somTD_SOMReleaseMutexSem * SOMDLINK SOMReleaseMutexSem;
  846. SOMEXTERN WIN32_DLLIMPORT somTD_SOMDestroyMutexSem * SOMDLINK SOMDestroyMutexSem;
  847. #endif
  848.  
  849. /*----------------------------------------------------------------------
  850.  *  Replaceable SOM Thread Identifier Operation
  851.  *
  852.  *  This operation is used by the SOM Kernel to index data unique to the
  853.  *  currently executing thread.  It must return a small integer that
  854.  *  uniquely represents the current thread within the current process.
  855.  */
  856. #if !defined(_WIN32)
  857. SOMEXTERN somTD_SOMGetThreadId * SOMDLINK SOMGetThreadId;
  858. #else
  859. SOMEXTERN WIN32_DLLIMPORT somTD_SOMGetThreadId * SOMDLINK SOMGetThreadId;
  860. #endif
  861.  
  862. /*----------------------------------------------------------------------
  863.  * Externals used in the implementation of SOM, but not part of the
  864.  * SOM API.
  865.  */
  866.  
  867. SOMEXTERN SOMObject * SOMLINK somTestCls(SOMObject *obj, SOMClass *classObj,
  868.                                          string fileName, int lineNumber);
  869. SOMEXTERN void SOMLINK somTest(int condition, int severity, string fileName,
  870.                                int lineNum, string msg);
  871. SOMEXTERN void SOMLINK somAssert(int condition, int ecode,
  872.                                  string fileName, int lineNum, string msg);
  873.  
  874.  
  875. #endif /* somapi_h */
  876.