home *** CD-ROM | disk | FTP | other *** search
/ io Programmo 39 / IOPROG_39.ISO / SOFT / sdkjava40.exe / data1.cab / fg_Include / Include / comattr.h next >
Encoding:
C/C++ Source or Header  |  2000-05-04  |  39.9 KB  |  1,087 lines
  1. //*************************************************************************
  2. // (C)Copyright 1995-1999  Microsoft Corporation, All rights reserved.
  3. //
  4. // Note: This document is an early release of the final specification. It is
  5. // meant to specify and accompany software that is still in development. Some
  6. // of the information in this documentation may be inaccurate or may not be an
  7. // accurate representation of the functionality of the final specification
  8. // or software. Microsoft assumes no responsibility for any damages that might
  9. // occur either directly or indirectly from these inaccuracies. Microsoft may
  10. // have trademarks, copyrights, patents or pending patent applications, or
  11. // other intellectual property rights covering subject matter in this document.
  12. // The furnishing of this document does not give you a license to these
  13. // trademarks, copyrights, patents, or other intellectual property rights
  14. //
  15. // This header file describes the _Java Class File Attributes_ that must
  16. // be present in any class file that is to be used to invoke a COM object
  17. // from Java, or expose a Java object as a COM object.
  18. //
  19. // Data type sizes:
  20. //
  21. //   BYTE       - 8 bits
  22. //   WORD       - 16 bits
  23. //   DWORD      - 32 bits
  24. //
  25. // BYTEs, WORDs and DWORDs are all unsigned and stored in the .class
  26. // in _Big-Endian_ format.
  27. //
  28. //
  29. // Alignment:
  30. //    There is no implicit padding between the fields of the structures,
  31. //    or any padding after the last field of any structure.
  32. //
  33. //
  34. // Attribute List:
  35. // ---------------
  36. //
  37. //   Level  Name                          Description
  38. //   -----  ----                          -----------
  39. //   Class  COM_Class_Type                Denotes the implementation language
  40. //   Class  COM_GuidPool                  Stores IID's and CLSID's.
  41. //   Class  COM_CustData                  Stores typelib custom data (CUSTDATA)
  42. //   Class  COM_MethodPool                Stores distilled typelib information
  43. //   Method COM_ExposedAs_Group           Exposes a Java method to COM.
  44. //   Method COM_ProxiesTo                 Exposes a COM method to Java.
  45. //   Field  COM_MapsTo                    Exposes external data to Java
  46. //
  47. //
  48. //
  49. // All unused bits in Flag fields must be zero.
  50. //
  51. //*************************************************************************
  52.  
  53.  
  54. #ifndef COMATTR_H
  55. #define COMATTR_H
  56.  
  57. #include <pshpack1.h>
  58.  
  59.  
  60. //========================================================================
  61. // Attribute Name:  COM_Class_Type
  62. // Attribute Level: Class
  63. // Restrictions:
  64. //    If the class type is MCCTCT_JCW, the access flags for the
  65. //      class must be a subset of:
  66. //
  67. //          ACC_PUBLIC
  68. //          ACC_FINAL
  69. //          ACC_ABSTRACT
  70. //
  71. //    If the class type is MCCTCT_JCDW, the access flags for the
  72. //      class must be a subset of:
  73. //
  74. //          ACC_PUBLIC
  75. //          ACC_FINAL (required)
  76. //
  77. //    The class's superclass must be java.lang.Object or a JCDW class.
  78. //
  79. //
  80. //
  81. // Attribute elements:
  82. // 
  83. //     WORD Flags
  84. //         CCTF_NODYNAMICIFCCASTS:
  85. //            This bit is legal only if the ClassType is MCCTCT_JCW.
  86. //
  87. //            If on, instances of this class can only be legally
  88. //            casts to interfaces explicitly implemented by either
  89. //            the instance's class or one of its ancestors.
  90. //
  91. //            If off, instances of this class can be cast at runtime
  92. //            to any interface which contains a methodpool item,
  93. //            provided that the underlying COM object returns a valid
  94. //            interface for the IID of the interface.
  95. //
  96. //
  97. //         CCTF_CHARSIZEMASK
  98. //
  99. //            These bits must be zero unless ClassType is MCCTCT_JCDW.
  100. //
  101. //            Otherwise, these bits indicate the treatment of certain
  102. //            string and character array types:
  103. //
  104. //              CCTF_CHARSIZEDUAL       -- dual mode
  105. //              CCTF_CHARSIZEANSI       -- ansi
  106. //              CCTF_CHARSIZEUNICODE    -- unicode
  107. //
  108. //
  109. //     WORD ClassType
  110. //         The only legal values are MCCTCT_JCW and MCCTCT_JCDW.
  111. //
  112. //         The actual type of a class is determined as follows:
  113. //
  114. //           If no ancestor class (including the class itself) has a
  115. //           COM_Class_Type attribute, the type is "pure".
  116. //
  117. //           If the class has no COM_Class_Type attribute but a single ancestor
  118. //           (which must be a direct descendant of java.lang.Object) has a
  119. //           COM_Class_Type attribute JCW, the type is "Derived from JCW."
  120. //
  121. //           If the class has a COM_Class_Type attribute, of type "MCCTCT_JCW",
  122. //           the class type is "JCW."
  123. //
  124. //           If the class has a COM_Class_Type attribute, of type
  125. //           "MCCTCT_JCDW", the class type is "JCDW."
  126. //
  127. //           All other situations are illegal.
  128. //
  129. //
  130. //     WORD CLSIDIndex
  131. //
  132. //          If ClassType is not MCCTCT_JCW, the contents of the field
  133. //          must 0xffff.
  134. //
  135. //          If the ClassType is MCCTCT_JCW, and the CLSIDIndex is
  136. //          not 0xffff, it must indicate a valid index into the
  137. //          GuidPool. The GUID corresponding to this index will be
  138. //          used as the CLSID of the COM object to load when
  139. //          an instance of this class is created using the "new"
  140. //          operator.
  141. //========================================================================
  142.  
  143. #define CCTF_NODYNAMICIFCCASTS 0x0001
  144.  
  145. #define CCTF_CHARSIZEMASK      0x0006
  146. #define CCTF_CHARSIZEDUAL      0x0000    
  147. #define CCTF_CHARSIZEANSI      0x0002
  148. #define CCTF_CHARSIZEUNICODE   0x0004
  149.  
  150. #define MCCTCT_JCW      ((WORD)1)
  151. #define MCCTCT_JCDW     ((WORD)2)
  152.  
  153. typedef struct {
  154.     WORD        Flags;          // CCTF_* value.
  155.     WORD        Classtype;      // MCCTCT_JCW or MCCTCT_JCDW
  156.     union {
  157.         WORD        CLSIDIndex;     // Optional index to CLSID (-1 for none)
  158.         struct {
  159.             BYTE    packing;    //1,2,4 or 8 (0xff defaults to 4 for backward compatibility)
  160.             BYTE    reserved1;  // must set to 0xff
  161.         } jcdw;
  162.     };
  163. } MCClassType;
  164.  
  165. // for compatibility with users of older headers.
  166. typedef MCClassType MCCT_Attr;
  167.  
  168.  
  169. //========================================================================
  170. // Attribute Name:  COM_GuidPool
  171. // Attribute Level: Class
  172. //
  173. // Restrictions:
  174. //   The class access flags must be a subset of:
  175. //      ACC_PUBLIC
  176. //      ACC_FINAL
  177. //      ACC_INTERFACE
  178. //      ACC_ABSTRACT
  179. //
  180. //
  181. // This attribute stores the IID's and CLSID's that are referenced by index
  182. // from the MethodPool. Valid indices range from 0 inclusive to nGuids
  183. // exclusive. The index 0xffff is reserved to indicate the "null" index.
  184. // Hence, the GuidPool can contain a maximum of 65535 guids.
  185. //
  186. // Attribute elements:
  187. //
  188. //      WORD nGuids
  189. //
  190. //         This field indicates the number of GUID's defined in this
  191. //         table.
  192. //
  193. //
  194. //      GUID aGuid[nGuids]
  195. //
  196. //         This array stores the actual GUID representations.
  197. //========================================================================
  198. typedef struct {
  199.     WORD        nGuids;         // # of guids in table
  200.     // GUID     aGuid[nGuids];
  201. } MCGuidPool;
  202.  
  203. // for compatibility with users of older headers.
  204. typedef MCGuidPool MCGP_Attr;
  205.  
  206.  
  207. //========================================================================
  208. // Attribute Name:  COM_CustData
  209. // Attribute Level: Class
  210. //
  211. // Restrictions:
  212. //   The class access flags must be a subset of:
  213. //      ACC_PUBLIC
  214. //      ACC_FINAL
  215. //      ACC_INTERFACE
  216. //      ACC_ABSTRACT
  217. //
  218. // This attribute exposes type library CUSTDATA elements.  Callers may
  219. // query a classes type library at runtime (such as through
  220. // IProvideClassInfo) for these attributes using methods like
  221. // ITypeInfo2::GetCustData.
  222. //
  223. // Attribute elements:
  224. //
  225. //      WORD nCustDatas
  226. //
  227. //          This field indicates the number of aCustData's defined in this
  228. //          table.
  229. //
  230. //      WORD aCustData[].GuidIndex
  231. //
  232. //          Index into the COM_GuidPool table.  Represents the GUID
  233. //          identity for this custom data element.
  234. //
  235. //      WORD aCustData[].DataIndex
  236. //
  237. //          Index into this classes constant pool.  Only certain types of
  238. //          constant pool entries are supported (currently CP_Utf8 and
  239. //          CP_Integer).
  240. //
  241. //========================================================================
  242. typedef struct {
  243.     WORD        nCustDatas;     // # of elements in table
  244.     // {
  245.     //      WORD GuidIndex;
  246.     //      WORD DataIndex;
  247.     // }        aCustData[nCustDatas];
  248. } MCCustData;
  249.  
  250. // for compatibility with users of older headers.
  251. typedef MCCustData MCCDP_Attr;
  252.  
  253.  
  254. //========================================================================
  255. // Attribute Name:  COM_MethodPool
  256. // Attribute Level: Class
  257. //
  258. // Restrictions:
  259. //   The class access flags must be a subset of:
  260. //      ACC_PUBLIC
  261. //      ACC_FINAL
  262. //      ACC_INTERFACE
  263. //      ACC_ABSTRACT
  264. //
  265. //   Though the MCFuncDesc structure allows you to specify an IID for
  266. //   individual MCFuncDesc, the Virtual Machine requires that all MCFuncDesc's
  267. //   in a .class file reference the same IID in the GuidPool.
  268. //
  269. //   (This restriction does not apply to IID's embedded in the MCTypeDesc's
  270. //   within the parameter arrays and return types of the MCFuncDesc's.)
  271. //
  272. //
  273. // This attributes stores the "method signatures" of the COM methods
  274. // that are invoked by and implemented by the Java methods in the .class
  275. // file. These "signatures" (MCFuncDesc's) are referenced by index by
  276. // other attributes in the class. Valid indices range from 0 inclusive to 
  277. // nFuncs exclusive. The index 0xffff is reserved to indicate
  278. // the "null" index.
  279. //
  280. //
  281. // Attribute elements:
  282. //
  283. //      WORD nFuncs;
  284. //
  285. //          This field indicates the number of MCFuncDesc's defined in this
  286. //          table.
  287. //
  288. //      MCFuncDesc aFuncDesc[nFuncs]
  289. //
  290. //          This array stores the actual MCFuncDesc's. MCFuncDesc's
  291. //          are variable-sized structure.
  292. //========================================================================
  293. typedef struct {
  294.     WORD        nFuncs;         // # of functions in table
  295.     // MCFuncDesc aMCFunc[nFuncs]
  296. } MCMethodPool;
  297.  
  298. // for compatibility with users of older headers.
  299. typedef MCMethodPool MCMP_Attr;
  300.  
  301.  
  302. //========================================================================
  303. // Structure: MCTypeDesc
  304. //
  305. // This structure describes the type of a parameter or return value
  306. // of a COM method.
  307. //
  308. // Structure elements:
  309. //
  310. //    BYTE Type
  311. //
  312. //       See the TD_* enumeration below.
  313. //
  314. //       TD_VOID is permitted only as the return type of a function.
  315. //
  316. //
  317. //
  318. //    BYTE Flags
  319. //
  320. //       The flags are grouped into in/out flags, thread-model flags,
  321. //        and attribute flags.
  322. //
  323. //        In/Out:
  324. //          If the MCTypeDesc is used to describe a parameter, the flags
  325. //          must specify one of TDF_IN, TDF_OUT or TDF_INOUT. For all types
  326. //          other than TD_PTR, TD_SAFEARRAY and TD_JARR, the value of
  327. //          this subflag must be TD_IN.
  328. //
  329. //          If the MCTypeDesc is used to describe a return value or a
  330. //          MapsTo type, this subflag must be set to zero.
  331. //
  332. //
  333. //        Threading Model:
  334. //          This subflag is meaningful only for the TD_INTF type.
  335. //          For all others, it must be set to zero.
  336. //          This subflag indicates the expected Threading Model of
  337. //          of the interface pointer. If the Virtual Machine creates
  338. //          a JCW to represent this COM interface, it will do the
  339. //          appropriate marshaling. If this TypeDesc is being
  340. //          used to marshal to a Java class that is not a JCW,
  341. //          this subflag must be have the value TDF_NOMARSHAL.
  342. //
  343. //          In certain cases, the Virtual Machine may produce a Java object
  344. //          that assumes a less restrictive threading model than is
  345. //          indicated by this subflag. This can happen if the
  346. //          interface pointer had been previously marshaled to Java
  347. //          through another method whose parameter was flagged with
  348. //          the less restrictive threading model. It can also happen
  349. //          if the incoming interface pointer was created by the
  350. //          Virtual Machine itself (these interface pointers are all
  351. //          free-threaded.)
  352. //
  353. //      *** NEW FOR SDK 3.2 ***
  354. //        Attributes:
  355. //          These flags are used only on method parameters and return
  356. //          values of type TD_JARR and TD_INTF- they should not be set
  357. //          in a MapsTo attribute.
  358. //          These flags indicate that a second parameter will be used
  359. //          to dynamically describe this parameter in some way (similar
  360. //          to iid_is and size_is in MIDL).
  361. //          There are currently two supported flags:
  362. //            TDF_USES_IID_IS:
  363. //              This flag is meaningful only for the TD_INTF type, and
  364. //              signifies that the IID of the interface parameter is
  365. //              determined dynamically at runtime using the value of
  366. //              another parameter.
  367. //
  368. //            TDF_USES_SIZE_IS:
  369. //              This flag is meaningful only for the TD_JARR type, and
  370. //              signifies that the size of the array parameter is
  371. //              determined dynamically at runtime using the value of
  372. //              another parameter.
  373. //      *** END NEW ***
  374. //
  375. //
  376. //   union {
  377. //      WORD    IIDIndex;       // for TD_INTF, if TDF_USES_IID_IS is not set.
  378. //      WORD    SizeIndex;      // for TD_STRUCT
  379. //      WORD    wSize;          // for TD_SYSFIXEDSTRING, TD_FIXEDARRAY, and TD_JARR
  380. //      WORD    wiHookClass;    // for TD_CUSTOM, TD_CUSTOMBYREF, and TD_CUSTOMBYVAL
  381. //      VARTYPE VarType;        // for TD_SAFEARRAY
  382. //      struct {
  383. //          BYTE    biParam;    // for TD_JARR, if TDF_USES_SIZE_IS is set,
  384. //                              //  and TD_INTF, if TDF_USES_IID_IS is set
  385. //          BYTE    bReserved;
  386. //      } a;
  387. //   }
  388. //
  389. //          For types other than TD_STRUCT, TD_INTF, TD_SAFEARRAY,
  390. //          TD_SYSFIXEDSTRING, TD_FIXEDARRAY, TD_JARR, TD_CUSTOM,
  391. //          TD_CUSTOMBYREF, and TD_CUSTOMBYVAL this union must be
  392. //          set to zero.
  393. //
  394. //          If the type is TD_STRUCT, this field must be set to
  395. //          an index into the constant-pool: the constant pool item
  396. //          must be type CP_Integer and must indicate the size of
  397. //          the struct in bytes.
  398. //
  399. //          If the type is TD_SYSFIXEDSTRING, TD_FIXEDARRAY, or
  400. //          TD_JARR, this field must be set to the number of elements
  401. //          in the array.
  402. //
  403. //      *** NEW FOR SDK 3.2 ***
  404. //          If the type is TD_JARR, and TDF_USES_SIZE_IS is specified
  405. //           in the flags, this field (a.biParam) is the zero-based index
  406. //           of the parameter that determines the dynamic (runtime) size
  407. //           of this array parameter.  The referenced parameter must be of
  408. //           integral or array of integral type.  This is similar to the
  409. //           MIDL attribute/concept "size_is".  a.bReserved must be set
  410. //           to zero.
  411. //      *** END NEW ***
  412. //
  413. //          If the type is TD_INTF, this field must be set to a valid
  414. //          index into the GuidPool. 0xffff (the "null" index) is not
  415. //          valid.
  416. //
  417. //      *** NEW FOR SDK 3.2 ***
  418. //          If the type is TD_INTF, and TDF_USES_IID_IS is specified
  419. //           in the flags, this field (a.biParam) is the zero-based index
  420. //           of a parameter that determines the dynamic (runtime) IID
  421. //           of this interface parameter.  The referenced parameter must
  422. //           be of "struct" or array of "struct" type.  This is similar to
  423. //           the MIDL attribute/concept "iid_is".  a.bReserved must be set
  424. //           to zero.
  425. //      *** END NEW ***
  426. //
  427. //          If the type is TD_CUSTOM, TD_CUSTOMBYREF, or TD_CUSTOMBYVAL,
  428. //          this field must be set to an index into the constant-pool:
  429. //          the constant pool item must be type CP_Class or CP_Utf8 (in
  430. //          which case the string is a class name) and specifies the class
  431. //          that will perform the custom marshaling.
  432. //
  433. //          If the type is TD_SAFEARRAY, this field must be set to
  434. //          a valid vartype that describes the element type.
  435. //          VT_ARRAY may not be set on this type.
  436. //          If VT_BYREF is set, this parameter will be interpreted
  437. //          as a SAFEARRAY** rather than a SAFEARRAY*.
  438. //
  439. //========================================================================
  440.  
  441. // MCTypeDesc enums
  442. #define TD_VOID     0x00
  443. #define TD_I1       0x01    //signed 8-bit
  444. #define TD_I2       0x02    //signed 16-bit
  445. #define TD_I4       0x03    //signed 32-bit
  446. #define TD_I8       0x04    //signed 64-bit
  447. #define TD_U1       0x05    //unsgnd 8-bit
  448. #define TD_U2       0x06    //unsgnd 16-bit
  449. #define TD_U4       0x07    //unsgnd 32-bit
  450. #define TD_U8       0x08    //unsgnd 64-bit
  451. #define TD_R4       0x09    //32-bit float
  452. #define TD_R8       0x0a    //64-bit float
  453. #define TD_PTR      0x0b    //ptr to data
  454. #define TD_STRUCT   0x0c    //byval struct (requires size)
  455. #define TD_INTF     0x0d    //IUnknown* derivative
  456. #define TD_JSTR     0x0e    //JString
  457. #define TD_JARR     0x0f    //JArray
  458. #define TD_VARIANT  0x10    //Variant
  459. #define TD_CUSTOM   0x11    //custom type
  460. #define TD_CUSTOMBYREF 0x12 //custom type byref
  461. #define TD_CUSTOMBYVAL 0x13 //custom type byval
  462. #define TD_SAFEARRAY 0x14      //SafeArray
  463. #define TD_SYSCHAR  0x15       //Unicode char or ansi char, depending on platform setting
  464. #define TD_SYSFIXEDSTRING 0x16 //Fixed ansi/unicode string (for use inside structs: SizeIndex == #ofchars, including null terminator)
  465. #define TD_FIXEDARRAY 0x17     //Fixed size array of scalares (for use inside structs: SizeIndex == # of elements)
  466. #define TD_OBJECT   0x18    //Field type of "L<something>". Treat as embedded struct if JCDW; treat as COM ifc if Object or Ifc.
  467.  
  468. // MCTypeDesc flags
  469. #define TDF_INOUTMASK       (TDF_IN|TDF_OUT)
  470. #define TDF_IN              0x01
  471. #define TDF_OUT             0x02
  472. #define TDF_INOUT           (TDF_IN|TDF_OUT)
  473.  
  474.  
  475. // Note: We overload TDF_LCID with TDF_AUTOMARSHAL - since TDF_LCID
  476. // is only valid on integer types, and TDF_AUTOMARSHAL is only valid
  477. // on interface types.
  478. #define TDF_LCID            0x04
  479.  
  480. #define TDF_AUTOMARSHAL     0x04
  481. #define TDF_NOMARSHAL       0x08
  482. #define TDF_THREADMODELMASK (TDF_AUTOMARSHAL|TDF_NOMARSHAL)
  483.  
  484. // attributes- valid only for interfaces (TD_INTF) and arrays (TD_JARR).
  485. #define TDF_PARAM_DEPENDENCY    0x10
  486. #define TDF_USES_IID_IS         TDF_PARAM_DEPENDENCY    // for TD_INTF
  487. #define TDF_USES_SIZE_IS        TDF_PARAM_DEPENDENCY    // for TD_JARR
  488.  
  489. #define TDF_USER1           0x80
  490. #define TDF_USER2           0x40
  491. #define TDF_USERMASK        (TDF_USER1|TDF_USER2)
  492.  
  493.  
  494. // Describes a single parameter or return value or type of field.
  495. typedef struct {
  496.     BYTE        Type;           // TD_* value
  497.     BYTE        Flags;          // TDF_* flags
  498.     union {
  499.         WORD    IIDIndex;       // for TD_INTF, if TDF_USES_IID_IS is not set.
  500.         WORD    SizeIndex;      // for TD_STRUCT
  501.         WORD    wSize;          // for TD_SYSFIXEDSTRING, TD_FIXEDARRAY, and TD_JARR
  502.         WORD    wiHookClass;    // for TD_CUSTOM, TD_CUSTOMBYREF, and TD_CUSTOMBYVAL
  503.         VARTYPE VarType;        // for TD_SAFEARRAY
  504.         struct {
  505.             BYTE    biParam;    // for TD_JARR, if TDF_USES_SIZE_IS is set,
  506.                                 //  and TD_INTF, if TDF_USES_IID_IS is set
  507.             BYTE    bReserved;
  508.         } a;
  509.     };
  510. } MCTypeDesc;
  511.  
  512.  
  513. //========================================================================
  514. // Structure: MCVtblMethod
  515. //
  516. // This structure describes a vtable-based method in a COM interface.
  517. // References to this structure can appear in both ExposedAs_Group
  518. // attributes and ProxiesTo attributes.
  519. //
  520. // Elements:
  521. //      WORD IIDIndex
  522. //
  523. //        A valid index into the GuidPool that describes the IID of
  524. //        the COM interface that implements this method.
  525. //        0xffff is not valid here.
  526. //
  527. //
  528. //      WORD VtblIndex
  529. //
  530. //        Denotes which vtable element the method occupies.
  531. //        The values 0, 1 and 2 are not legal here since these correspond
  532. //        to the IUnknown* methods which cannot be overridden.
  533. //        In addition, if the methodpool contains MCDispMethod's
  534. //        using the same IID, values 3,4,5,6 must be avoided (as
  535. //        they correspond to IDispatch* methods which are supplied
  536. //        by the Virtual Machine.)
  537. //
  538. //
  539. //      WORD nArguments
  540. //        The number of parameters in the aParamType[] element. This
  541. //        count does not include the automatic "this" parameter passed
  542. //        to all COM methods.
  543. //
  544. //        If the wRetValParameter element is 0xffff, this count must match
  545. //        the number of parameters in the corresponding Java signature
  546. //        exactly. Otherwise, the count must be exactly one greater than
  547. //        the corresponding Java signature.
  548. //
  549. //
  550. //      WORD wRetValParameter
  551. //        If this element contains a value other than 0xffff, it must
  552. //        contains a value between 0 (inclusive) and nArguments (exclusive).
  553. //        This indicates that the parameter whose index is equal to
  554. //        wRetValParameter is actually a pointer through which the
  555. //        method returns its "true" return value. The aParamType for
  556. //        this parameter must indicate the type of the buffer (the
  557. //        "pointer to" is implicit), and the RetType must be TD_VOID.
  558. //        In addition, the return type of the Java method sig must
  559. //        be compatible with the retval parameter.
  560. //
  561. //        If this COM method is invoked from Java, the Virtual Machine
  562. //        will supply a return value buffer of the appropriate type
  563. //        to the COM method. Upon a successful return from the COM method,
  564. //        (see MCFuncDesc.Flags for what constitutes a successful return).
  565. //
  566. //        If Java is used to implement this COM method, the Virtual Machine
  567. //        will remove the retval pointer parameter from the list of arguments
  568. //        presented to the Java method. When the Java method returns,
  569. //        the Virtual Machine will convert the Java method's return value
  570. //        to COM representation, then write it to the retval buffer
  571. //        passed in from COM. The Virtual Machine will then create
  572. //        a COM return value that indicates success (see MCFuncDesc.Flags for
  573. //        what constitutes a successful return.)
  574. //
  575. //      MCTypeDesc RetType
  576. //        Describes the return type. This type must be TD_VOID if
  577. //        wRetValParameter contains a value other than 0xffff, or
  578. //        if MCFuncDesc.Flags has the MCMDF_HRESULT_RETVAL bit set.
  579. //
  580. //      MCTypeDesc aParamType[nArguments]
  581. //        Describes the parameter of each COM method.
  582. //
  583. //      *** NEW FOR VERSION 4.0 ***
  584. //         If MCMDF_HRESULT_RETVAL|MCMDF_IGNORE_NONFAILING_HRESULTS are both
  585. //         set and wRetValParameter == -1 and the Java method's return type
  586. //         is 'Z' (boolean), the VM will transform:
  587. //
  588. //              true               <--> S_OK
  589. //              false              <--> S_FALSE
  590. //              throw ComException <--> other
  591. //
  592. //
  593. //========================================================================
  594. typedef struct {
  595.     WORD        IIDIndex;
  596.     WORD        VtblIndex;
  597.     WORD        nArguments;
  598.     WORD        wRetValParameter;   // -1 means none
  599.     MCTypeDesc  RetType;
  600.     // Followed by array of MCTypeDesc's for parameters
  601.     MCTypeDesc  aParamType[1];
  602. } MCVtblMethod;
  603.  
  604.  
  605.  
  606. // These values intentionally match the VT_* enum values that are allowed
  607. // in a VARIANT.
  608. #define VTD_EMPTY    ((BYTE)0)
  609. #define VTD_NULL     ((BYTE)1)
  610. #define VTD_I2       ((BYTE)2)
  611. #define VTD_I4       ((BYTE)3)
  612. #define VTD_R4       ((BYTE)4)
  613. #define VTD_R8       ((BYTE)5)
  614. #define VTD_CY       ((BYTE)6)
  615. #define VTD_DATE     ((BYTE)7)
  616. #define VTD_BSTR     ((BYTE)8)
  617. #define VTD_DISPATCH ((BYTE)9)
  618. #define VTD_ERROR    ((BYTE)10)
  619. #define VTD_BOOL     ((BYTE)11)
  620. #define VTD_VARIANT  ((BYTE)12)
  621. #define VTD_UNKNOWN  ((BYTE)13)
  622. #define VTD_UI1      ((BYTE)17)
  623.  
  624. // Modifiers to VTD_ types. These do not have the same values as their VT_*
  625. // equivalents because those values don't fit in a byte.
  626. #define VTD_BYREF   ((BYTE)0x80)
  627. #define VTD_ARRAY   ((BYTE)0x40)
  628.  
  629.  
  630. //========================================================================
  631. // Structure: MCVarTypeDesc
  632. //
  633. //   Describes the type of a single parameter or return value to an
  634. //   IDispatch method.
  635. //
  636. // Elements:
  637. //
  638. //      BYTE type
  639. //          This field contains a "compressed VARTYPE" value, defined
  640. //          by the VTD_* values.
  641. //
  642. //      WORD optname
  643. //          If non-zero, this field must be a constant-pool index to
  644. //          a CP_Utf8 which gives the name of the parameter.
  645. //          This field is optional.
  646. //
  647. //      BYTE Flags
  648. //
  649. //       The flags are grouped into in/out and thread-model flags.
  650. //
  651. //        In/Out:
  652. //          If the MCVarTypeDesc is used to describe a parameter, the flags
  653. //          must specify one of TDF_IN, TDF_OUT or TDF_INOUT.  If "type" does
  654. //          not have VTD_BYREF set, TDF_IN must be specified (TDF_INOUT is
  655. //          illegal in this case).
  656. //
  657. //          If the MCVarTypeDesc is used to describe a return value this
  658. //          subflag must be set to zero.
  659. //
  660. //
  661. //        Threading Model:
  662. //          This subflag is meaningful only for the VTD_DISPATCH and
  663. //          VTD_UNKNOWN types.  For all others, it must be set to zero.
  664. //          See the description for MCTypeDesc.Flags- the same values
  665. //          and semantics apply.
  666. //
  667. //========================================================================
  668. typedef struct {
  669.     BYTE        type;         //VTD_* value
  670.     WORD        optname;      //(0 or constant-pool index to utf8)
  671.     BYTE        Flags;        // TDF_* values
  672. } MCVarTypeDesc;
  673.  
  674.  
  675. //========================================================================
  676. // Structure: MCDispMethod
  677. //
  678. //  This structure describes an Ole Automation method or property.
  679. //
  680. // Elements:
  681. //      WORD IIDIndex
  682. //         This field must be a valid index into the GUID pool and
  683. //         denotes the IID (typically IID_IDispatch, but can be any
  684. //         interface that derives from IDispatch.) through which
  685. //         this method is exposed.
  686. //
  687. //      DWORD Dispid
  688. //         Specifies the DISPID of this method or property.
  689. //
  690. //      WORD disptype
  691. //         Describes the dispmember type. One of: 
  692. //           DISPATCH_PROPERTYGET
  693. //           DISPATCH_PROPERTYPUT
  694. //           DISPATCH_PROPERTYPUTREF
  695. //           DISPATCH_METHOD
  696. //
  697. //      WORD dispname
  698. //         If this field is non-zero, it must be a valid index into
  699. //         constant-pool and the index must reference a CP_Utf8 which
  700. //         provides the name of the method. This field is required
  701. //         only if the MCDispMethod is referenced by an ExposedAs_Group
  702. //         attribute.
  703. //
  704. //      WORD nArguments
  705. //         The number of arguments.
  706. //
  707. //      MCVarTypeDesc RetType
  708. //         Describes the type of the return value.
  709. //
  710. //      MCVarTypeDesc aParamType[nArguments]
  711. //         Describes the type of each parameter.
  712. //========================================================================
  713. typedef struct {
  714.     WORD           IIDIndex;
  715.     DWORD          Dispid;
  716.     WORD           disptype;    
  717.     WORD           dispname;
  718.     WORD           nArguments;
  719.     MCVarTypeDesc  RetType;
  720.     // Followed by array of MCVarTypeDesc's for parameters
  721.     MCVarTypeDesc  aParamType[1];
  722. } MCDispMethod;
  723.  
  724.  
  725. //========================================================================
  726. // Structure: MCCustomMethod
  727. //
  728. //  This structure describes a COM vtable method that uses a custom
  729. //  method marshaling hook (Dispatch and dual methods cannot be
  730. //  custom marshaled.) This feature is only supported in IE4 or later.
  731. //
  732. // Elements:
  733. //      WORD IIDIndex
  734. //         This field must be a valid index into the GUID pool and
  735. //         denotes the IID through which this method is exposed.
  736. //
  737. //      WORD VtblIndex
  738. //
  739. //        Denotes which vtable element the method occupies.
  740. //        The values 0, 1 and 2 are not legal here since these correspond
  741. //        to the IUnknown* methods which cannot be overridden.
  742. //        In addition, if the methodpool contains MCDispMethod's
  743. //        using the same IID, values 3,4,5,6 must be avoided (as
  744. //        they correspond to IDispatch* methods which are supplied
  745. //        by the Virtual Machine.)
  746. //
  747. //
  748. //      WORD hookclsIndex
  749. //
  750. //        Index of a CONSTANT_Class constant-pool item which
  751. //        denotes the Java class that holds the hook methods.
  752. //        This class should derive directly from java.lang.Object
  753. //        to avoid circular loading problems.
  754. //
  755. //
  756. //      WORD j2cmethodIndex
  757. //
  758. //        Index of a CONSTANT_Utf8 constant-pool item which
  759. //        denotes the method within the hook class that is to
  760. //        handle Java->COM calls. The method should have the prototype:
  761. //
  762. //          public static JTYPE j2chook(int)
  763. //
  764. //        where JTYPE must be identical to the return type of
  765. //        the associated Java method, with one exception: if the
  766. //        associated Java method returns a reference type (object
  767. //        or array), JTYPE can be declared as "java.lang.Object".
  768. //
  769. //
  770. //     WORD c2jmethodIndex
  771. //
  772. //        Index of a CONSTANT_Utf8 constant-pool item which
  773. //        denotes the method within the hook class that is to
  774. //        handle COM->Java calls. The method should have the prototype:
  775. //
  776. //          public static void c2jhook(int)
  777. //
  778. //
  779. //     WORD cbUserData
  780. //
  781. //        Number of bytes of user data following the paramFlavor[] array.
  782. //        The VM will not interpret this data but will make it available
  783. //        to the hook methods. This allows one hook method to handle
  784. //        multiple methods.
  785. //
  786. //
  787. //     DWORD reserved
  788. //        Reserved for future use. Must set to 0.
  789. //
  790. //
  791. //     BYTE bRetFlavor
  792. //        Certain platforms have calling conventions that require
  793. //        distinguishing between normal and floating point values.
  794. //        See the MCARGF_* values for the possible flavors.
  795. //        Because COM methods almost universally return HRESULT's,
  796. //        this field will usually be set to MCARGF_I4. This field
  797. //        cannot be used to indicate the flavor of an [out,retval]
  798. //        parameter (these need to be set in the paramFlavor[] array -
  799. //        the flavor is MCARGF_PTR).
  800. //
  801. //     BYTE cbSpecialComArgs
  802. //        Indicates the size of the paramFlavor[] array.
  803. //
  804. //
  805. //     MCSpecialArgumentEntry paramFlavor[cbSpecialComArgs]
  806. //        Note: This is a variable length array and is not
  807. //        indicated in the struct definition. It follows the 
  808. //        cbSpecialComArgs field.
  809. //
  810. //        Indicates the flavor of all parameters that are *not*
  811. //        type MCARGF_I4, *or* the final parameter. The final parameter
  812. //        must always be declared because on some platforms, the
  813. //        total size of the argument stack is needed to implement
  814. //        stdcall calling correctly. The fields of an MCSpecialArgumentEntry
  815. //        are:
  816. //            bArgIndex:
  817. //               where 0 denotes the first 4-byte argument after the "this"
  818. //               pointer, 1 denotes the second 4-byte argument after the'
  819. //               "this" pointer and so forth. The "this" pointer is
  820. //               implicitly MCARGF_PTR, so it's flavor need not (and cannot)
  821. //               be indicated in this table.
  822. //
  823. //            bArgFlavor:
  824. //               Must be one of the MCARGF_* values.
  825. //
  826. //     BYTE  userData[cbUserData]
  827. //        Note: This is a variable length array and is not
  828. //        indicated in the struct definition. It follows the 
  829. //        cbSpecialComArgs field.
  830. //
  831. //        Any userdata associated with this method. The VM does
  832. //        not interpret this data but hook methods can access it.
  833. //
  834. //
  835. //========================================================================
  836.  
  837. #define MCARGF_I4     0       // 4-byte integer
  838. #define MCARGF_R4     1       // 4-byte floating point
  839. #define MCARGF_R8     2       // 8-byte floating point
  840. #define MCARGF_I8     3       // 8-byte integer
  841. #define MCARGF_PTR    4       // machine address
  842. #define MCARGF_STRUCT 5       // structure (takes up two slots: slot following
  843.                               //   is the size of the structure in bytes.)
  844.  
  845.  
  846. typedef struct {
  847.     BYTE            bArgIndex;      // index of argument
  848.     BYTE            bArgFlavor;     // See MCARGF_* constants
  849. } MCSpecialArgumentEntry;
  850.  
  851. typedef struct {
  852.     WORD            IIDIndex;
  853.     WORD            VtblIndex;
  854.     WORD            hookclsIndex;   //hook class
  855.     WORD            j2cmethodIndex; //name of method for Java->COM marshaling
  856.     WORD            c2jmethodIndex; //name of method for COM->Java marshaling
  857.     WORD            cbUserData;     // # of bytes of user data
  858.     DWORD           reserved;       // must be 0: reserved for future use.
  859.     BYTE            bRetFlavor;     // see MCARGF_* constants
  860.     BYTE            cbSpecialComArgs; // # of non-I4 com arguments
  861.  
  862. // Following this is the paramFlavor[] array.
  863. // Following that are bytes of user data ("cbUserData" bytes in all.)
  864. } MCCustomMethod;
  865.  
  866.  
  867. //========================================================================
  868. // Structure: MCFuncDesc
  869. //
  870. // This structure describes a single method in the method pool.
  871. //
  872. // Elements:
  873. //      WORD  cbSize
  874. //        The size of the entire MCFuncDesc (including the cbSize field)
  875. //        in bytes.
  876. //
  877. //      WORD Flags
  878. //         MCMDF_DISPATCH
  879. //            This flag indicates that the function is a Dispatch method.
  880. //
  881. //         MCMDF_HRESULT_RETVAL
  882. //            This flag may not be used together with MCMDF_DISPATCH.
  883. //            This flag indicates that the return type of the
  884. //             method is an HRESULT and that it is to be mapped to
  885. //             an exception on the Java side.
  886. //
  887. //            If this flag is used, the declared type of the RetVal
  888. //             must be TD_VOID. 
  889. //
  890. //            When this flag is on, the Virtual Machine will treat
  891. //             all return values from COM objects as hresults and
  892. //             will throw a Java exception (details TBD) if the hresult
  893. //             is not S_OK.
  894. //
  895. //             Conversely, the Virtual Machine will map all uncaught
  896. //             exceptions from Java code into a failing HRESULT,
  897. //             and will supply a return value of S_OK otherwise.
  898. //
  899. //         *** NEW FOR VERSION 4.0 ***
  900. //         MCMDF_IGNORE_NONFAILING_HRESULTS
  901. //            This flag may not be used together with MCMDF_DISPATCH.
  902. //
  903. //            This flag works in conjunction with MCMDF_HRESULT_RETVAL.
  904. //            If set, only HRESULT's that have the high bit (FAIL)
  905. //            set will generate a Java exception. Non-zero HRESULT's
  906. //            that do not set the bit (such as S_FALSE) will not
  907. //            generate an exception.
  908. //
  909. //
  910. //
  911. //
  912. //========================================================================
  913.  
  914. // Structure name: MCFuncDesc.
  915. #define MCMDF_DISPATCH       0x0001
  916. #define MCMDF_HRESULT_RETVAL 0x0002   // legal only if !MCMDF_DISPATCH
  917. #define MCMDF_IGNORE_NONFAILING_HRESULTS 0x0004   // legal only if !MCMDF_DISPATCH
  918.  
  919. #define MCMDF_CUSTOM         0x0008   // legal only if !(MCMDF_DISPATCH|MCMDF_HRESULT_RETVAL|MCMDF_IGNORE_NONFAILING_HRESULTS)
  920.  
  921. typedef struct {
  922.     WORD        cbSize;         // size of entire MCFuncDesc in bytes
  923.     WORD        Flags;          // MCMCDF_* values
  924.     union {
  925.         MCVtblMethod mvm;
  926.         MCDispMethod mdm;
  927.         MCCustomMethod mcm;
  928.     };
  929. } MCFuncDesc;
  930.  
  931.  
  932. //========================================================================
  933. // Attribute Name:   COM_ExposedAs_Group
  934. // Attribute Level:  Method
  935. // Restrictions:
  936. //    The access flags for the method must be a subset of:
  937. //
  938. //      ACC_PUBLIC
  939. //      ACC_PRIVATE
  940. //      ACC_PROTECTED
  941. //      ACC_FINAL
  942. //      ACC_SYNCHRONIZED
  943. //      ACC_NATIVE
  944. //      ACC_ABSTRACT
  945. //
  946. // The ExposedAs_Group is a collection of ExposedAs structures, each
  947. // of which causes the Java method to be exposed as a COM method.
  948. //
  949. // Attribute Elements:
  950. //    WORD Flags
  951. //      Must be 0.
  952. //
  953. //    WORD nExposedAs
  954. //      # of ExposedAs attributes that follow.
  955. //
  956. //    MCEA ExposedAs[nExposedAs]
  957. //      Array of exposed as.
  958. //========================================================================
  959.  
  960. typedef struct _Microsoft_COM_ExposedAs_Group {
  961.     WORD       Flags;           //none defined
  962.     WORD       nExposedAs;
  963.     // followed by array of MCExposedAs's.
  964. } MCExposedAsGroup;
  965.  
  966. // for compatibility with users of older headers.
  967. typedef MCExposedAsGroup MCEAG_Attr;
  968.  
  969.  
  970. //========================================================================
  971. // Structure:  _Microsoft_COM_ExposedAs
  972. //
  973. // Each ExposedAs structure causes the Java method to be exposed as a COM
  974. // method.
  975. // Elements:
  976. //    WORD Flags
  977. //      Must be 0.
  978. //
  979. //    WORD MethodPoolIndex
  980. //      Must be a valid index into the MethodPool.
  981. //========================================================================
  982. typedef struct _Microsoft_COM_ExposedAs {
  983.     WORD        Flags;
  984.     WORD        MethodPoolIndex;
  985. } MCExposedAs;
  986.  
  987. // for compatibility with users of older headers.
  988. typedef MCExposedAs MCEA;
  989.  
  990.  
  991. //========================================================================
  992. // Attribute Name:   COM_ProxiesTo
  993. // Attribute Level:  Method
  994. // Restrictions:
  995. //    The access flags for the method must be a subset of:
  996. //
  997. //      ACC_PUBLIC
  998. //      ACC_PRIVATE
  999. //      ACC_PROTECTED
  1000. //      ACC_FINAL
  1001. //      ACC_NATIVE (required)
  1002. //      ACC_ABSTRACT (on interfaces only)
  1003. //
  1004. //
  1005. // The ProxiesTo attribute denotes that the Java method is implemented
  1006. // using COM.
  1007. //
  1008. // Attribute Elements:
  1009. //    WORD MCP_Flags
  1010. //      Must be 0.
  1011. //
  1012. //    WORD MethodPoolIndex
  1013. //      Must be a valid index into the MethodPool.
  1014. //========================================================================
  1015. typedef struct _Microsoft_COM_ProxiesTo {
  1016.     WORD        MCP_Flags;
  1017.     WORD        MethodPoolIndex;
  1018. } MCProxiesTo;
  1019.  
  1020. // for compatibility with users of older headers.
  1021. typedef MCProxiesTo MCPT_Attr;
  1022.  
  1023.  
  1024. //========================================================================
  1025. // Attribute Name:   COM_MapsTo
  1026. // Attribute Level:  Field
  1027. // Restrictions:
  1028. //    The access flags for the field must be a subset of:
  1029. //
  1030. //      ACC_PUBLIC
  1031. //      ACC_PRIVATE
  1032. //      ACC_PROTECTED
  1033. //      ACC_FINAL
  1034. //
  1035. //
  1036. // The MapsTo attribute denotes that the data for the field is actually
  1037. // stored in externally allocated memory.
  1038. //
  1039. // Attribute Elements:
  1040. //    WORD Flags
  1041. //      MTF_AUTOOFFSET:
  1042. //          If this flag is set, dwOffset must be 0 and the offset will
  1043. //          be computed by the Virtual Machine for the hosting platform.
  1044. //          This allows the structure definition to move freely between
  1045. //          platforms.
  1046. //
  1047. //          Every MapsTo in a .class file must use the same setting
  1048. //          for MTF_AUTOOFFSET.
  1049. //
  1050. //          The auto-packing algorithm for the x86 platform is ???.
  1051. //
  1052. //    WORD wPad
  1053. //      Must be 0
  1054. //
  1055. //    DWORD dwOffset
  1056. //      The offset in bytes within the external data structure.
  1057. //      If MTF_AUTOOFFSET is on, this field has no meaning and must be
  1058. //      set to 0.
  1059. //
  1060. //    MCTypeDesc typedesc
  1061. //      Describes the native type of the field..
  1062. //========================================================================
  1063. typedef struct _Microsoft_COM_MapsTo {
  1064.     WORD        Flags;      // MTF_* values
  1065.     WORD        wPad;
  1066.     DWORD       dwOffset;
  1067.     MCTypeDesc  typedesc;
  1068. } MCMapsTo;
  1069.  
  1070. // for compatibility with users of older headers.
  1071. typedef MCMapsTo MCMT_Attr;
  1072.  
  1073.  
  1074. #define MTF_AUTOOFFSET 0x0001
  1075.  
  1076.  
  1077. // These are defined only for backward compatibility with older sources.
  1078. // New code should not use these names.
  1079. #define TDF_SINGLE          0x00
  1080. #define TDF_APARTMENT       TDF_AUTOMARSHAL
  1081. #define TDF_FREE            TDF_NOMARSHAL
  1082.  
  1083.  
  1084. #include <poppack.h>
  1085.  
  1086. #endif // COMATTR_H
  1087.