
VB Declaration Converter   v 1.3 for NT 3.51
Copyright Exile Software 1995

Public Domain
Please notify me of incorrent or unusable declarations which you may discover!
Thanks.

Before translating SDK headers:
	1. Run the app and select ' File|Build export list '.  This will extract a list of exported functions from the SYSTEM32 directory.
	(Note: Use an NT installation's system files. W95 files don't work properly.)
	2. Copy the file produced (exportlist.txt) from the '... \save' subdirectory to the ' ...\exportlist' subdirectory.
	3. The app must have this file by this name in this place to resolve 'Lib' imports.
	4. Be forewarned that translating the entire SDK is a lengthy process (15 minutes or more).
 
1. Description

    The Declaration Converter  reads WIN32 SDK header files and converts C prototypes to VB declarations.
    The Converter also reads "win32api.txt" and similar text files containing VB declarations and sorts and converts them to a form suitable for importing into a database.
     The VB declarations are separated into lists of Constants, Types, Functions, and Subs and sorted alphabetically.  The declarations can then be processed to shorten then.  The declaration lists can be saved to a single file, or to four seperate files.

2. Usage

    Reading VB files:    The Converter can read MS or other texts of VB declarations.    Declarations are extracted and sorted and can be processed to shorten them.    Keywords are stripped ("Type/End Type", "Declare Sub", "Declare Function", "Const") so that the output can be used with a tool which looks up API declarations.    (This speeds searches, reduces file sizes, and provides flexibility when pasting the declarations into VB projects.)

    Reading C headers:    The Converter can read WIN32 SDK header files and convert C prototypes to VB declarations.  See the notes below before using these declarations.

    Processing:    The declarations can be processed in the following ways:
       	1. Comments can be stripped
        	2. Datatypes can be converted to the shortened form (e.g.  "As Long" > "&"). (Functions and Subs only)
        	3. Variable names can be shortened. (Functions and Subs only) 
    
    Editing:    Individual items can be edited, added, removed, or copied to the clipboard.

************************************************************************************************************************************

Notes on converting C prototypes to VB declarations


1. Untranslated terms.   In several cases, C expressions are not translated.  This may happen if there is no VB equivalent of the expression, or if a decision is required by the user before the declaration can be used.
        a. Bit-fields are not translated. (See 'alphaops.h')
        b. Unions are not translated.  You must remove the union declaration and replace it with one or more variables which fit your intended usage.
        c. Structures and unions which occur within structures are not translated.  Again, replace these with one or more  variables of the same size.
        d. Unrecognized C datatypes are not translated.   These datatypes will be declared by their original name.

2. Discards.   Discarded lines are added to a "Discards" list.  Check this list whenever you translate a file.  As many lines as possible are ommited for the sake of clarity, but it may still be cluttered.

3. 'Lib'.  Because there is no indication in the header files of which dll contains which function, the Converter  must have a list of exported functions before it can resolve API (and other Dll) calls.   Build the "exportlist.txt" file as described above.   The Converter will look up function names from this list.  If a function is not in the list, the converter will write:
        Lib "x.dll"
Functions not found are placed in a seperate list.

4. Arrays.   C arrays which are sized by C constants will be 1 too large. This is compensated for by declaring arrays " ( 1 to x)".   '[*]' is translated 'ANYSIZE-ARRAY'.  Undimensioned arrays are noted as such in the comment.

5. Pointers.   If a pointer cannot be otherwise typed, it is translated "As Long".
        C Structures which contain pointers to structures or functions should not normally be used from VB.   ( Ex: "HD_NOTIFY", from "commctrl.h")
        C Structures which contain pointers to chars, bytes, and strings are marked with a warning comment when translated.
        Pointers to functions, interfaces, and classes are translated "As Long".

6. ANSI/Wide functions.  Functions which have both an ANSI and a Wide form are aliased to the ANSI version.   Wide versions of functions are not translated.

7. ANSI/Wide structures.   Both ANSI and Wide structures are translated.   The Wide version of a structure should not ordinarily be used from VB.

8. LARGE_INTEGER.   This structure is not translated because of problems parsing it.

9. 'TCHAR'.   Datatypes which can be compiled to ANSI or Wide are interpreted as ANSI (one-byte).

10. Inline functions.   The prototype for inline functions are not  translated.

11. Constants.   Most "#define" statements are translated as constants.   Macros are discarded.

12. Enumerated types.   Enumerated types are translated with a prefix "ENUM_" and the body commented out.

13 OLE.   A lot of OLE-related stuff isdiscarded because it can't be used from VB.

************************************************************************************************************************************

Function Parameters.

1. 'As Any'.    'As Any' is used by MS to flag functions which contain parameters which can accept a string or numerical argument.  You should never use this in VB; instead create aliases such as FooByNum/FooByString. 
    I have found no way to detect such parameters; LPVOID is translated 'As Any'.   You must create the aliases when you find you need them.

2. 'ByRef/ByVal'.   This version supplies the 'ByRef' or 'ByVal' qualifier for function declarations.   C Integers and Longs are translated as Long.   Character types are translated as Byte or String. Wide chars are translated as integers or ' Array(1 to 2*(size)) As Byte '.

3. Pointers to Arrays.   Pointers to arrays are translated as the array's datatype and passed ByRef.   Pass the first element of the array when calling the function.   Ex: "ArrayName(0)".

4. Pointers to numbers.   In general, pointers are translated as the datatype they point to and passed ByRef.   This causes VB to create a pointer and pass it to the function.

5. Pointers to Strings.   Strings work exactly the opposite to numbers.  Pointers to strings are translated as String passed ByVal.   VB will create a pointer to the String and pass it to the function.

6. BSTR.  BSTR are translated as String, passed ByRef.

7. Pointers to functions.   Pointers to functions are translated as Long.   You must have a dll containing the callback function to use these functions from VB, and the dll will probably manage such calls itself.

8. Variable names.   Many C function prototypes list only the datatype of parameters.   Arbitrary names are provided for these variables.     

9. Unrecognized datatypes.   If a datatype is not recognized, it is transliterated.   Check the 'Discard' list or the header file if the datatype is not apparent.  

10. Hardcoded argument values.    A few functions have hardcoded argument values.   These are rendered with the C value as the datatype.  Ex: ( ' x as 0x16 ' )

************************************************************************************************************************************

Known Problems.


1. Some constructions cannot be parsed correctly. Consider the following, from "winnt.h":
	#if defined(MIDL_PASS)
	typedef struct _LARGE_INTEGER {
	#else // MIDL_PASS
	typedef union _LARGE_INTEGER {
   	 struct {
       	 DWORD LowPart;
       	 LONG HighPart;
  	  };
    	struct {
       	 DWORD LowPart;
       	 LONG HighPart;
   	 } u;
	#endif //MIDL_PASS
	    LONGLONG QuadPart;
	} LARGE_INTEGER;
The converter returns this unchanged, but only because it recognizes it explicitly.   Other such constructions will cause parsing errors, because the converter performs text parsing.  It ignores preprocessing directives.   It works against the WIN32 SDK headers because it was designed for the style of constructions which appear therein, but keep this in mind if translating other header files.  It is not intended as a general purpose C translator, but it will work against many many SDK samples and other files which use similar coding convevtions.

2. In general, the converter requires you to manually check for accuracy and usabilty before attempting to incorpoate the output in a VB project.   I haven't systematically checked the output for usability, so check the SDK documentation when a problem arises. 

3. I am trying to bring the output to as close a match to correct VB declarations as can be gotten from an examination of header files.   If you have any suggestions, please post me a message.

Ed@scling.hk.super.net
CS: 100267,546
