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