home *** CD-ROM | disk | FTP | other *** search
/ Power GUI Programming with VisualAge C++ / powergui.iso / trialva / ibmcppw / include / somobj.idl < prev    next >
Encoding:
Text File  |  1996-02-21  |  14.7 KB  |  419 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. //
  13.  
  14. //  SOMObject: System Object Model root class
  15.  
  16. #ifndef somobj_idl
  17. #define somobj_idl
  18.  
  19. interface SOMClass;
  20. interface SOMObject;
  21.  
  22. /* 
  23.  *  Define a value large enough to be used in typedefs for character
  24.  *  arrays that need to be able to hold the largest legal file name.
  25.  */
  26. #define FILENAME_MAX 260
  27.  
  28. /*
  29.  *  IDL does not provide for the use of the type "int".
  30.  *  Although the mapping of a user-defined type named "int" to the
  31.  *  IDL type long, given here, is both binary and source compatible 
  32.  *  on AIX and OS/2 2.x, it is still bad form, since the C type "int"
  33.  *  can vary from platform to platform.  This is here only for migration
  34.  *  of OIDL to IDL.  All new IDL files should explicitly select long or
  35.  *  short (as appropriate) instead of "int."
  36.  */
  37. typedef long int;
  38.  
  39. /*
  40.  *  The following types are commonly used in C programming
  41.  */
  42. typedef octet uchar_t;
  43. typedef    unsigned long size_t;
  44.  
  45. /* 
  46.  *  We define SOMFOREIGN as an anchor within the IDL type system for 
  47.  *  "foreign" types that are not expressible in IDL.  Foreign types
  48.  *  can be used at a class implementer's discretion, but we discourage
  49.  *  their use except within "private" sections of an IDL definition.
  50.  *  If you decide to define a foreign type, you must do so by setting
  51.  *  up a typedef for it and then supplying an "impctx" modifier (within
  52.  *  your implementation section) that designates the implementation
  53.  *  context where your type is understood.  You can also optionally
  54.  *  supply a "length" modifier that indicates the number of bytes 
  55.  *  needed to hold an instance of the foreign type.  The FILE type
  56.  *  below is an example of a foreign type useful in C programming.
  57.  *  The impctx modifier is attached to the FILE type in the SOMObject
  58.  *  implementation section.
  59.  */  
  60.  
  61. #ifndef _SOMFOREIGN_DEFINED_
  62.   #define _SOMFOREIGN_DEFINED_
  63.   #ifdef __SOMIDL__
  64.     typedef void * SOMFOREIGN;
  65.   #else
  66.     typedef unsigned long SOMFOREIGN;
  67.   #endif /* __SOMIDL__ */
  68. #endif /* !_SOMFOREIGN_DEFINED_ */
  69.  
  70. typedef SOMFOREIGN FILE;
  71. #pragma modifier FILE: impctx = C, length = 0;
  72.  
  73. /*  
  74.  *  "va_list" is used to represent a standard parameter list constructed
  75.  *  by a caller for functions or methods that can accept a variable number
  76.  *  of arguments.
  77.  */
  78. typedef SOMFOREIGN va_list;
  79. #pragma modifier va_list: impctx = C;
  80.  
  81. /* 
  82.  *  "SOMHANDLE" is used within SOM to represent arguments whose value
  83.  *  is uninterpretted.
  84.  */
  85. typedef SOMFOREIGN SOMHANDLE;
  86. #pragma modifier SOMHANDLE: impctx = SOM;
  87. typedef void* somToken;
  88.  
  89. /*
  90.  *  "somId" is used to refer to the efficient case-insensitive string
  91.  *  representation used by many SOM run-time methods.
  92.  */
  93. typedef SOMFOREIGN somId;
  94. #pragma modifier somId: impctx = SOM;
  95.  
  96. /*
  97.  *  Kinds of TypeCodes, per CORBA 1.1, p.139 
  98.  */
  99. enum TCKind {
  100.     tk_null, tk_void,
  101.     tk_short, tk_long, tk_ushort, tk_ulong,
  102.     tk_float, tk_double, tk_boolean, tk_char,
  103.     tk_octet, tk_any, tk_TypeCode, tk_Principal, tk_objref,
  104.     tk_struct, tk_union, tk_enum, tk_string,
  105.     tk_sequence, tk_array,
  106.  
  107.     /* SOM extensions follow: */
  108.     tk_pointer, /* tk_pointer takes a parameter list with 1 argument:  */
  109.         /* tk_pointer {TypeCode} - The TypeCode describes the  */
  110.         /* type that the pointer references.               */
  111.     tk_self,    /* tk_self takes a parameter list with 1 argument:     */
  112.         /* tk_self {name} - The name refers to an enclosing    */
  113.         /* struct or union.  This type, when combined with     */
  114.         /* tk_pointer above, permits the existence of self-    */
  115.         /* -referential pointers in a struct or union.           */
  116.     tk_foreign  /* tk_foreign takes a parameter list with 2 arguments: */
  117.         /* tk_foreign {context, length} - The context is a     */
  118.         /* string that designates an implementation domain     */
  119.         /* where the foreign type is understood.  The length   */
  120.         /* parameter is optional, but if supplied indicates    */
  121.         /* the size of an instance of the type.                */ 
  122. };
  123.  
  124. /* 
  125.  *  Types defined only for compatibility with SOM Release 1
  126.  */
  127. typedef char integer1;
  128. typedef short integer2;
  129. typedef unsigned short uinteger2;
  130. typedef long integer4;
  131. typedef unsigned long uinteger4;
  132. typedef float float4;
  133. typedef double float8;
  134. typedef string zString;                 /* NULL terminated string */
  135. typedef string fString;                 /* non-terminated string  */
  136.  
  137. // The following typedefs are based on somapi.h and somcorba.h, which
  138. // define the published API form of internal SOM data structures.
  139. // We provide these typedefs here in their IDL form primarily to
  140. // satisfy the IDL compiler, which requires that all methods declared
  141. // using IDL have known argument types. Also, as a result of this
  142. // approach, the interface repository will contain the "public" types
  143. // for SOM internal data structures -- not the actual types.
  144.  
  145. /* -- Special procedure pointer types */
  146. typedef somToken somMethodProc;
  147. typedef somToken somMethodPtr;
  148.  
  149. /* -- Public Method Table Structure */
  150. struct somMethodTab {
  151.     SOMClass classObject;
  152. };
  153.  
  154. /*  -- Public Object Instance Structure */
  155. struct SOMAny {
  156.     somMethodTab  *mtab;
  157. };
  158.  
  159. /* -- Public Method and Data Tokens */
  160. typedef somToken somMToken;
  161. typedef somToken somMLocator;
  162. typedef somToken somDToken;
  163. typedef somToken somDLocator;
  164. typedef somToken somClassInfo;
  165. typedef somToken SOMTokBuf;
  166. typedef somToken somInitCtrl;
  167. typedef somToken somInitInfo;
  168. typedef somToken somDestructCtrl;
  169. typedef somToken somDestructInfo;
  170. typedef somToken somAssignCtrl;
  171. typedef somToken somAssignInfo;
  172.  
  173. typedef unsigned long somRdAppType; /* method signature encoding */
  174.  
  175. struct somMethodInfo {
  176.     somRdAppType       callType;
  177.     long               va_listSize;
  178.     unsigned long      *float_map;
  179. } ;
  180.  
  181. /* -- Method descriptor structure */
  182. typedef struct somMethodDataStruct {
  183.     somId id;
  184.     long type;                    /* 0=static, 1=dynamic, 2=nonstatic */
  185.     somId descriptor;             /* for use with IR interfaces */
  186.     somMToken mToken;             /* NULL for dynamic methods */
  187.     somMethodPtr method;      /* depends on resolution context */
  188.     somToken *shared;
  189. } somMethodData;
  190.  
  191. /* -- For building lists of class objects */
  192. struct somClassList {
  193.     SOMClass cls;
  194.     somClassList *next;
  195. };
  196. typedef somClassList *somClasses; 
  197.  
  198. typedef somToken somObjects;
  199. /* -- For building lists of method tables */ 
  200. struct somMethodTabList {
  201.     somMethodTab      *mtab;
  202.     somMethodTabList  *next;
  203. };
  204. typedef somMethodTabList *somMethodTabs;
  205. typedef somMethodTabList *somParentMtabStructPtr;
  206.  
  207. /* -- Generic ClassData structure */
  208. struct somClassDataStructure {
  209.     SOMClass classObject;
  210.     somToken tokens[1];
  211. };
  212.  
  213. /* -- Generic Auxiliary Class Data Structure */
  214. struct somCClassDataStructure {
  215.     somMethodTabs parentMtab;
  216.     somDToken instanceDataToken;
  217.     somMethodPtr ptrs[1];
  218. };
  219. typedef somCClassDataStructure *somCClassDataStructurePtr;
  220.  
  221. typedef octet *somBooleanVector;
  222.  
  223. // exception enum constants found in somcorba.h
  224. enum exception_type { NO_EXCEPTION, USER_EXCEPTION, SYSTEM_EXCEPTION };
  225.  
  226. struct Environment { 
  227.     exception_type major;  // use somcorba.h exception_type values
  228.     octet opaque_data[12]; // #2990
  229. };
  230.  
  231. //
  232. //
  233. //-------------------------------------------------------------
  234. // SOMObject Interface Definition
  235. //
  236.  
  237. interface SOMObject
  238. // This is the SOM root class, all SOM classes must be descended from
  239. // <SOMObject>. <SOMObject> has no instance data so there is no
  240. // per-instance cost to to being descended from it.
  241.  
  242. {
  243.  
  244.   // a sequence of SOM Objects
  245.   typedef sequence <SOMObject> SOMObjectSequence;
  246.  
  247.   // a sequence of booleans. 
  248.   typedef sequence <octet> BooleanSequence;
  249.  
  250.   // a structure to describe an object-related offset, and
  251.   // a sequence of class-related offsets
  252.   struct somObjectOffset {    
  253.      SOMObject obj;
  254.      long     offset;
  255.   };
  256.   typedef sequence <somObjectOffset> somObjectOffsets;
  257.  
  258.   void somDefaultInit(inout somInitCtrl ctrl);
  259.   // A default initializer for a SOM object. Passing a null ctrl 
  260.   // indicates to the receiver that its class is the class of the
  261.   // object being initialized, whereby the initializer will determine
  262.   // an appropriate control structure.
  263.  
  264.   void somDestruct(in octet doFree, inout somDestructCtrl ctrl);
  265.   // The default destructor for a SOM object. A nonzero <doFree>
  266.   // indicates that the object storage should be freed by the
  267.   // object's class (via somDeallocate) after uninitialization.
  268.   // As with somDefaultInit, a null ctrl can be passed.
  269.  
  270.   void somDefaultCopyInit(inout somInitCtrl ctrl, in SOMObject fromObj);
  271.   // A default copy constructor. Use this to make copies of objects for
  272.   // calling methods with "by-value" argument semantics.
  273.  
  274.   SOMObject somDefaultAssign(inout somAssignCtrl ctrl, in SOMObject fromObj);
  275.   // A default assignment operator. Use this to "assign" the state of one
  276.   // object to another.
  277.  
  278.   void somDefaultConstCopyInit(inout somInitCtrl ctrl, in SOMObject fromObj);
  279.   // A default copy constructor that uses a const fromObj.
  280.  
  281.   void somDefaultVCopyInit(inout somInitCtrl ctrl, in SOMObject fromObj);
  282.   // A default copy constructor that uses a volatile fromObj.
  283.  
  284.   void somDefaultConstVCopyInit(inout somInitCtrl ctrl, in SOMObject fromObj);
  285.   // A default copy constructor that uses a const volatile fromObj.
  286.  
  287.   SOMObject somDefaultConstAssign(inout somAssignCtrl ctrl, 
  288.                                   in SOMObject fromObj);
  289.   // A default assignment operator that uses a const fromObj.
  290.  
  291.   SOMObject somDefaultVAssign(inout somAssignCtrl ctrl, in SOMObject fromObj);
  292.   // A default assignment operator that uses a volatile fromObj.
  293.  
  294.   SOMObject somDefaultConstVAssign(inout somAssignCtrl ctrl, 
  295.                                    in SOMObject fromObj);
  296.   // A default assignment operator that uses a const volatile fromObj.
  297.  
  298.   void somInit();
  299.   // Obsolete but still supported. Override somDefaultInit instead of somInit.
  300.  
  301.   void somFree();
  302.   // Obsolete but still supported. Use somDestruct with a nonzero
  303.   // <doFree> instead.
  304.  
  305.   void somUninit();
  306.   // Obsolete but still supported. Override somDestruct instead of somUninit.
  307.  
  308.   SOMClass somGetClass();
  309.   // Return the receiver's class.
  310.  
  311.   string somGetClassName();
  312.   // Return the name of the receiver's class.
  313.  
  314.   long somGetSize();        
  315.   // Return the size of the receiver.
  316.  
  317.   boolean somIsA(in SOMClass aClassObj);
  318.   // Returns 1 (true) if the receiver responds to methods
  319.   // introduced by <aClassObj>, and 0 (false) otherwise.
  320.  
  321.   boolean somIsInstanceOf(in SOMClass aClassObj);
  322.   // Returns 1 (true) if the receiver is an instance of
  323.   // <aClassObj> and 0 (false) otherwise.
  324.  
  325.   boolean somRespondsTo(in somId mId);
  326.   // Returns 1 (true) if the indicated method can be invoked
  327.   // on the receiver and 0 (false) otherwise.
  328.  
  329.   boolean somDispatch(out somToken retValue, 
  330.                    in somId methodId, 
  331.                    in va_list ap);
  332.   // This method provides a generic, class-specific dispatch mechanism.
  333.   // It accepts as input <retValue> a pointer to the memory area to be
  334.   // loaded with the result of dispatching the method indicated by
  335.   // <methodId> using the arguments in <ap>. <ap> contains the object 
  336.   // on which the method is to be invoked as the first argument.
  337.  
  338.   boolean somClassDispatch(in SOMClass clsObj, 
  339.                         out somToken retValue, 
  340.                         in somId methodId, 
  341.                         in va_list ap);
  342.   // Like somDispatch, but method resolution for static methods is done
  343.   // according to the clsObj instance method table.
  344.  
  345.   boolean somCastObj(in SOMClass cls);
  346.   // cast the receiving object to cls (which must be an ancestor of the
  347.   // objects true class. Returns true on success.
  348.  
  349.   boolean somResetObj();
  350.   // reset an object to its true class. Returns true always.
  351.  
  352.  
  353.   SOMObject somPrintSelf();
  354.   // Uses <SOMOutCharRoutine> to write a brief string with identifying
  355.   // information about this object.  The default implementation just gives
  356.   // the object's class name and its address in memory.
  357.   // <self> is returned.
  358.  
  359.   void somDumpSelf(in long level);
  360.   // Uses <SOMOutCharRoutine> to write a detailed description of this object
  361.   // and its current state.
  362.   //
  363.   // <level> indicates the nesting level for describing compound objects
  364.   // it must be greater than or equal to zero.  All lines in the
  365.   // description will be preceeded by <2*level> spaces.
  366.   //
  367.   // This routine only actually writes the data that concerns the object
  368.   // as a whole, such as class, and uses <somDumpSelfInt> to describe
  369.   // the object's current state.  This approach allows readable
  370.   // descriptions of compound objects to be constructed.
  371.   //
  372.   // Generally it is not necessary to override this method, if it is
  373.   // overriden it generally must be completely replaced.
  374.  
  375.   void somDumpSelfInt(in long level);
  376.   // Uses <SOMOutCharRoutine> to write in the current state of this object.
  377.   // Generally this method will need to be overridden.  When overriding
  378.   // it, begin by calling the parent class form of this method and then
  379.   // write in a description of your class's instance data. This will
  380.   // result in a description of all the object's instance data going
  381.   // from its root ancestor class to its specific class.
  382.  
  383. #ifdef __SOMIDL__
  384.   implementation {
  385.     releaseorder: somInit,somUninit,somFree,somDefaultVCopyInit,
  386.           somGetClassName,somGetClass,somIsA,somRespondsTo,
  387.           somIsInstanceOf,somGetSize,somDumpSelf,somDumpSelfInt,
  388.           somPrintSelf,somDefaultConstVCopyInit,somDispatchV,
  389.           somDispatchL,somDispatchA, 
  390.                   somDispatchD,somDispatch,somClassDispatch,
  391.           somCastObj, somResetObj, somDefaultInit, somDestruct, 
  392.           somPrivate1, somPrivate2,
  393.           somDefaultCopyInit, somDefaultConstCopyInit, somDefaultAssign,
  394.           somDefaultConstAssign, somDefaultVAssign, 
  395.           somDefaultConstVAssign;
  396.  
  397.     // Class Modifiers
  398.     callstyle = oidl;
  399.     externalstem = somob; 
  400.     majorversion = 1; 
  401.     minorversion = 4; 
  402.     filestem = somobj;
  403.     dllname = "som.dll";
  404.  
  405.     // Public Method Modifiers    
  406.     somDefaultInit: init;
  407.     somDefaultCopyInit: init;
  408.     somDefaultConstCopyInit: init;
  409.     somDefaultVCopyInit: init;
  410.     somDefaultConstVCopyInit: init;
  411.     somGetClassName : dual_owned_result;             /* defect 11920 NSK */
  412.  
  413.   };
  414. #endif /* __SOMIDL__ */
  415. };
  416.  
  417. #endif  /* somobj_idl */
  418.  
  419.