home *** CD-ROM | disk | FTP | other *** search
/ io Programmo 39 / IOPROG_39.ISO / SOFT / sdkjava40.exe / data1.cab / fg_Include / Include / jexefmt.h < prev    next >
Encoding:
Text File  |  2000-05-04  |  15.3 KB  |  359 lines
  1. /*++
  2.  
  3. Copyright (c) 1995-1999  Microsoft Corporation.  All rights reserved.
  4.  
  5. Module Name:
  6.  
  7.     jexefmt.h
  8.  
  9. Abstract:
  10.  
  11.     The Microsoft VM has the ability to load .class files and other
  12.     Java visible resource files (images,audio clips,etc...) from Win32 PE
  13.     image files (.exe and .dll files).  In order for the VM to be able to 
  14.     find Java resources from within a PE, they must be stored within it as
  15.     Win32 resources.  This header file describes the format of the data 
  16.     that must be stored within the resources of a PE image in order for 
  17.     the VM to locate Java resources within that image.  This format is 
  18.     referred to as the exegen format herein.
  19.  
  20. Details:
  21.  
  22.   How the VM finds Win32 modules containing Java resources
  23.   --------------------------------------------------------        
  24.         
  25.     Assuming that you have a Win32 PE image that has Java resources bound
  26.     to it, there are three ways to tell the VM that it should look for 
  27.     resources within that module:
  28.     
  29.     1.  If the resources are bound into a DLL, then that DLL can be placed 
  30.         on the classpath.  The syntax is the same as how you would add a 
  31.         .zip file to the classpath.  The '.dll' extension must be specified.  
  32.         There is a restriction on how a DLL must be built in order to be 
  33.         placed on  the classpath.  In particular, the resource containing 
  34.         the file directory must be stored within a resource with a specific 
  35.         ID (see below).
  36.         
  37.     2.  The COM interface IJavaExecute2::SetClassSource can be used to add 
  38.         a Win32 module to the list of locations where the VM searches for 
  39.         Java resources.  See javaexec.h.
  40.         
  41.     3.  The RNI method AddModuleResourceClassSource can also be used to 
  42.         add a Win32 module to the list of locations where the VM searches 
  43.         for Java resources.  See native.h.
  44.         
  45.  
  46.   Different versions of the exegen format
  47.   ---------------------------------------
  48.     
  49.     There currently are two versions of the exegen format.  The original
  50.     format, version 1, only supported .class files, and could not store 
  51.     arbitrarily named resources.  The VMs of the IE4 era and before 
  52.     (anything earlier than VM version 4.79.2582) only support the version
  53.     1 format.  Newer VMs support the version 2 format which adds the 
  54.     ability to store non-class resources (images files,etc...).  The 
  55.     version 1 format also required that all of the data be stored within
  56.     a single Win32 resource, the version 2 format removes this 
  57.     restriction.
  58.  
  59.     
  60.   Version 1 format
  61.   ----------------
  62.   
  63.     All classes are stored in a single Win32 binary resource within the 
  64.     PE.  This resource begins with a table that lists the names of the 
  65.     files contained within the resource, and information that indicates 
  66.     where the raw bits for those files are located.  The actual data for the 
  67.     contained files follows this table.
  68.     
  69.     If IJavaExecute2::SetClassSource or AddModuleResourceClassSource is used
  70.     to tell the VM about the module, then this resource can be stored with 
  71.     any resource ID (although the resource type must be RT_RCDATA), since 
  72.     those APIs allow you to specify the resource ID.  If building a DLL to 
  73.     be placed on the classpath, then this resource must be stored with a 
  74.     resource ID of 1000 (JEX_DEFAULT_CLASS_RESOURCE_ID), and the resource 
  75.     type must be RT_RCDATA.
  76.     
  77.     The layout of the this resource consists of three sections, and is laid
  78.     out in this order:
  79.     
  80.      [JEXHEADER]
  81.      [FILEINFO SECTION]
  82.      [RAW DATA SECTION] 
  83.     
  84.     
  85.     1.  The resource begins with a header that contains a signature, a 
  86.         format version, flags, and a count of the number of class files 
  87.         contained within the resource.  The layout of the header is defined 
  88.         in the  JEXHEADER structure.  The dwFormatVersion of the JEXHEADER 
  89.         structure must be set to 1 for the version 1 format.
  90.         
  91.     2.  Immediately following the header is an array of file information 
  92.         structures.  The number of elements in this list is equal to the 
  93.         cNumFiles field in the header.  The format of these structures is 
  94.         
  95.         The layout of each of these file information structures is defined
  96.         in the JEXFILEINFOV1 structure.  Each specifies the name and location 
  97.         of a class file that is contained within the resource.
  98.         
  99.         Note that the dwNameOffset field points to the name of the class file.
  100.         This name must be in UTF8 form.  Forward slashes must be used as 
  101.         package separators.  The name is the class name, not the name of a 
  102.         class file, so do not append a '.class' onto the end.  So, for 
  103.         example, the following is correct:
  104.       
  105.         'java/lang/Class'
  106.         
  107.         But these are not:
  108.       
  109.         'java\lang\Class'
  110.         'java.lang.Class'
  111.         'java/lang/Class.class'
  112.         
  113.     3.  Following the list of JEXFILEINFOV1 structures is the string data for 
  114.         the class names, and raw binary data of the class files.  Note that 
  115.         there is no implied ordering on this data.  The only thing that must 
  116.         hold is that the resource offsets in the JEXFILEINFOV1 structures 
  117.         must point to the proper data.  The jexegen tool happens to place 
  118.         all of the string data immediately after the file information list, 
  119.         followed by the raw binary data of the class files, but there is no 
  120.         reason that any other generation tool needs to follow this layout.  
  121.  
  122.     
  123.   Version 2 format
  124.   ----------------
  125.  
  126.     The exegen version 2 format adds two features that the version 1 format 
  127.     did not support.
  128.  
  129.     1.  The ability to store arbitrarily named resources within the module.
  130.         This allows image files, audio clips, etc... to be stored in addition
  131.         to class files.  These named resources can be retrieved from the 
  132.         Java side with any APIs which can load classpath relative data (such 
  133.         as java.lang.Class.getResourceAsStream).
  134.     
  135.     2.  The ability to store the class/resource data in multiple Win32 
  136.         resources.  The version format required that all class data be 
  137.         contained within the exegen resource.  The version 2 format allows 
  138.         the class/resource data in Win32 resources other than the primary 
  139.         exegen resource.  This allows individual Java resources to be stored 
  140.         as individual Win32 resources.  Amongst other things, this opens up 
  141.         the possibility to utilize Win32 internationalization of resources on 
  142.         Java resources.
  143.         
  144.     As with the version 1 format, there is a primary exegen resource that 
  145.     contains the JEXHEADER and file information structures (although, the 
  146.     structure of these file information blocks has changed).  The rules for 
  147.     how the VM locates this information have not changed.  The resource 
  148.     identifier specified with either IJavaExecute2::SetClassSource or 
  149.     AddModuleResourceClassSource refers to this primary resource.  This main 
  150.     resource must be stored as resource ID JEX_DEFAULT_CLASS_RESOURCE_ID in
  151.     DLLs intended for the classpath.
  152.  
  153.     The layout of the main resource is essentially the same as before.  A 
  154.     header, followed by a list of file information structures, followed by 
  155.     string data and possibly file data.
  156.     
  157.     The JEXHEADER structure remains unchanged, with the exception that the 
  158.     dwFormatVersion field must be set to 2.
  159.  
  160.     Following the header is a list of JEXFILEINFOV2 structures.  The number
  161.     of elements in this list is determined by the cNumFiles field in the 
  162.     header.  These are similar to the JEXFILEINFOV1 structures, with the 
  163.     addition of two fields (ResourceID and ResourceType) which specify the 
  164.     Win32 resource which contains the bits for each Java resource.
  165.     
  166.     Following the list of JEXFILEINFOV2 structures is the string data for the 
  167.     file names, and resource names (if any).  Some of the java resource files
  168.     may be found here as well, although all of the file data may be found in
  169.     other resources.
  170.     
  171.     Note that the fields ResourceID and ResourceType do not contain Win32
  172.     resource IDs.  See the JEXRESID type for details of how map these
  173.     values to Win32 resource IDs.
  174.     
  175.     As in the version 1 format, the dwNameOffset field in the JEXFILEINFOV2 
  176.     structure is an offset to the name of the Java resource in UTF8 form.
  177.     Unlike the original format, this name is file name not a class name.
  178.     Class files must be stored with the '.class' extension.  Forward slashes
  179.     are used as package separators.  For example, the following is correct:
  180.     
  181.         'java/lang/Class.class'
  182.         
  183.     But these are not:
  184.       
  185.         'java\lang\Class.class'
  186.         'java.lang.Class.class'
  187.         'java/lang/Class'
  188.  
  189.     
  190.     The version 2 format gives a good deal of flexibility in how to layout
  191.     the Java resources within the exe/dll file.
  192.     
  193.     1.  Just like in the original format, the files can exist in the main
  194.         resource.  The ResourceID and ResourceType fields of the 
  195.         corresponding JEXFILEINFOV2 structures need to be set to 
  196.         JEX_MAINRESOURCE_MARKER.  The cbFileSize and dwDataOffset fields 
  197.         need to be filled in to specify where in the main resource the 
  198.         resource file is located.
  199.       
  200.     2.  You can have a one-to-one mapping between a java resource file and a
  201.         Win32 resource that it is located in.  ResourceID and ResourceType 
  202.         need to contain the proper values to point to the Win32 resource 
  203.         (either by name or integer IDs).  cbFileSize should be set to 
  204.         JEX_USE_RESOURCE_LENGTH to indicate that the size of the java 
  205.         resource is the same as the Win32 resource that it is found in.  
  206.         dwDataOffset should be 0.
  207.       
  208.     3.  You can have external Win32 resources (that is, not the main resource) 
  209.         that contain multiple java resources.  ResourceID and ResourceType 
  210.         point to the Win32 resource, and dwDataOffset and cbFileSize specify 
  211.         which portion of that Win32 resource contains the data for the 
  212.         Java resource.
  213.  
  214. --*/
  215.  
  216. #ifndef __HEADER_JEX
  217. #define __HEADER_JEX
  218.  
  219. #ifdef __cplusplus
  220. extern "C" {
  221. #endif
  222.  
  223. // Default resource ID for the main exegen resource.  Unless otherwise 
  224. // specified, the main data resource is looked for within a given PE at
  225. // this ID (the type is RT_RCDATA).  DLLs on the classpath must store
  226. // their exegen data at this resource ID.
  227.  
  228. #define JEX_DEFAULT_CLASS_RESOURCE_ID 1000
  229.  
  230. // Signature the begins the main exegen resource data.
  231.  
  232. #define JEX_RESOURCE_SIGNATURE        0x43524E44
  233.  
  234. // Resource Identifiers found in the JEXFILEINFOV2 structures.
  235. // Used to specify resource name IDs and resource type IDs.
  236. // Should be interpreted as follows:
  237. //
  238. //  - If set to 0xFFFFFFFF (JEX_MAINRESOURCE_MARKER), then indicates
  239. //    the main resource (the resource with the JEXHEADER in it).
  240. //
  241. //  - If the high bit is set, then the remainder of the high word 
  242. //    should be zeros, and the low word is a numeric Win32 
  243. //    resource identifier.  Use MAKEINTRESOURCE on the low word.
  244. //
  245. //  - Otherwise the value is interpreted as an offset from the 
  246. //    beginning of the main resource to a null-terminated Unicode
  247. //    string which contains the name of the resource ID or type.
  248.  
  249. typedef DWORD JEXRESID;
  250.  
  251. // Special case value for JEXRESIDs.  Specifies the main resource.
  252.  
  253. #define JEX_MAINRESOURCE_MARKER       0xFFFFFFFF
  254.  
  255. // Header found at the beginning of the main exegen data resource.
  256. //
  257. //   dwSignature - must be JEX_RESOURCE_SIGNATURE.
  258. //
  259. //   cNumFiles - indicates the number of file info structs 
  260. //               following the header.  The exact type of these
  261. //               file info structs depends on dwFormatVersion.
  262. //
  263. //   dwFormatVersion  - Currently must be either 1 or 2.
  264. //
  265. //   dwFlags - Currently unused, must be set to 0.
  266.  
  267. typedef struct
  268. {
  269.     DWORD  dwSignature;
  270.     DWORD  cNumFiles;
  271.     DWORD  dwFormatVersion;
  272.     DWORD  dwFlags;
  273. }
  274. JEXHEADER, *PJEXHEADER;
  275.  
  276. // Exegen version 1 file info structs.  A list of these follow
  277. // the JEXHEADER iff the dwFormatVersion field of the header is 
  278. // set to 1.  Each one of these describes a class file that is
  279. // contained within the jexegen'd PE image.
  280. //
  281. // NB: All data is contained within the main resource, so all
  282. // offsets are relative to the beginning of the main resource.
  283. //
  284. //  dwNameOffset - Offset from the beginning of the main resource
  285. //                 to a null terminated UTF8 string which contains
  286. //                 the name of the class file.  The names should 
  287. //                 not contain a '.class' extension.  Forward slashes
  288. //                 ('/') must be used as package separators.
  289. //
  290. //  dwDataOffset - Offset from the beginning of the main resource 
  291. //                 to the data for this class file.
  292. // 
  293. //  dwDataSize   - Length of the this class file in bytes.
  294.  
  295. typedef struct
  296. {
  297.     DWORD dwNameOffset;
  298.     DWORD dwDataSize;
  299.     DWORD dwDataOffset;
  300. }
  301. JEXFILEINFOV1, *PJEXFILEINFOV1;    
  302.  
  303. // Exegen version 2 file info structs.  A list of these follow
  304. // the JEXHEADER iff the dwFormatVersion field of the header is 
  305. // set to 2.  Each one of these describes a java resource file 
  306. // (class file,image file,etc...) that is contained within the 
  307. // jexegen'd PE image.
  308. //
  309. // NB: Unlike the V1 format, the data for each java resource file
  310. // may exist in Win32 resources other than the main one.  The
  311. // ResourceID and ResourceType fields specify which resource contains
  312. // the bits for the file.  
  313. //
  314. //  dwNameOffset - Offset from the beginning of the main resource
  315. //                 to a null terminated UTF8 string which contains
  316. //                 the name of the java resource.  Unlike the V1 
  317. //                 format the name must be a complete name (class 
  318. //                 files must be terminated with a '.class' extension).
  319. //                 Forward slashes ('/') must be used as package separators.
  320. //
  321. //  dwDataOffset - Offset from the beginning of the owning resource 
  322. //                 to the data for this java resource.  Must be 0 if
  323. //                 dwDataSize is set to 0xFFFFFFFF.
  324. // 
  325. //  dwDataSize   - If set to 0xFFFFFFFF (JEX_USE_RESOURCE_LENGTH),
  326. //                 then the length of the java resource is the size of 
  327. //                 the Win32 resource that it lives within.  Otherwise,
  328. //                 this value is simply the length of the java resource
  329. //                 in bytes.
  330. //
  331. //  ResourceID   
  332. //  ResourceType - These two fields specify the Win32 resource within
  333. //                 the exegen'd PE image which contains the bits for 
  334. //                 this java resource.  See JEXRESID for details of how
  335. //                 to map these values to an actual Win32 resource.
  336.  
  337. typedef struct
  338. {
  339.     DWORD    dwNameOffset;
  340.     DWORD    cbFileSize;
  341.     DWORD    dwDataOffset;
  342.     JEXRESID ResourceID;
  343.     JEXRESID ResourceType;
  344. }
  345. JEXFILEINFOV2, *PJEXFILEINFOV2;    
  346.  
  347. // Special case value for the JEXFILEINFOV2.cbFileSize field.
  348. // Indicates that the size of the file is that same as the size
  349. // of the Win32 resource that it lives in.
  350.  
  351. #define JEX_USE_RESOURCE_LENGTH       0xFFFFFFFF  
  352.                    
  353. #ifdef __cplusplus
  354. }
  355. #endif
  356.  
  357. #endif // __HEADER_JEX      
  358.  
  359.