[twinBASIC] WinDevLib - Windows Development Library for twinBASIC (oleexp+more)

[fafalone]

Windows Development Library for twinBASIC :: WinDevLib

Full Readme, additional info, browsable source, and copy of package at https://github.com/fafalone/WinDevLib. It's recommended that you add it to projects via the twinBASIC Package Manager.

WinDevLib is a project to make all common Windows API COM interfaces, DLL declares, and related Types/Enums/Consts available while programming in twinBASIC.
Included are definitions of 3300+ common COM interfaces and 10,000+ APIs from all the common system modules, a level of coverage which makes WDL an entirely different experience than any VBx library, the largest of which offer at most 1/10th as much with huge gaps.
This makes working with WDL similar to working in C++ with #include <Windows.h> and a number of other headers for commonly used features. These have all been redone by hand from the original headers, in order to restore 64bit type info lost in VB6 versions, avoid the errors of automated conversion tools (e.g. Win32API_PtrSafe.txt is riddled with errors), and make them friendlier by converting groups of constants associated with a variable into an Enum so it comes up in Intellisense.
oo
This project also serves a comprehensive twinBASIC replacement for oleexp.tlb, my Modern Shell Interfaces Type Library project for VB6. 100% of the content is covered with little to no change (see below for details).

Please report any bugs via the Issues feature here on GitHub.
Requirements

twinBASIC Beta 617 or newer is required..


Adding WinDevLib to your project

You have 2 options for this:
Via the Package Server

twinBASIC has an online package server and WinDevLib is published on it. Open your project settings and scroll to the Library References, then click 'Available Packages'. Add "Windows Development Library for twinBASIC v7.1.286" (or whatever the newest version is). "WinDevLib for Implements" contains Implements compatible versions of a small number of common interfaces not defined in a compatible way in the main project; you normally don't need this. For more details, including illustrations, see this post.

From a local file

You can download the project from this repository and use the .twinpack file. Navigate to the same area as above, and click on the "Import from file" button.

Guide to switching from oleexp.tlb

WinDevLib presented the best opportunity there would be to ditch some olelib legacy baggage. It's fairly simple to move your VB6 projects to WinDevLib, just follow these steps:

1. Replace oleexp.IUnknown with IUnknownUnrestricted. WinDevLib keeps this separate due to the major issues with conflicts with the former approach. If your project has IUnknown without oleexp. in front of it, do not replace those, as it's not referring to oleexp.
   
   
2. After you've done that, you can now go ahead and simply delete all remaining instances of oleexp. (including the .).
   
   
3. Convert Currency to LongLong for interfaces and APIs: It's no longer neccessary to worry about multiplying and dividing by 10,000 since tB supports a true 64bit type in both 32bit and 64bit mode. So this change is ultimately for the better, but existing codebases will have had to have used Currency for all interfaces and oleexp APIs expecting a 64bit integer.
   
   
4. Manually address any errors remaining. Interfaces should be mostly fine at this point, but if you've made use of the APIs in oleexp, many of them have syntax differences, mainly not being able to rewrite an ending [out] argument as the return value, and changing String arguments to LongPtr you'll need StrPtr with. Another major difference is that the default for almost all APIs with ANSI/Unicode (A/W) versions, is now the Unicode version. A notable exception is SendMessage due to the overwhelming amount of VBx code expecting it to mean SendMessageA. In most cases, the W version is declared with LongPtr for strings, and the untagged alias version uses tB's new DeclareWide keyword to disable ANSI conversion while using String.
   

Note that this is just for using WinDevLib -- you'll likely have a lot more changes to make if you want to make your project x64 compatible.

Guide to switching from oleexpimp.tlb

There's 'WinDevLib for Implements' (WinDevLibImpl.twinpack/.twinproj) as well, but you'll note it has substantially fewer interfaces than oleexpimp.tlb. This is because there's two reasons for an interface to have an alternate version: It uses [ Preservesig ] on one or more methods, or it uses As Any. twinBASIC allows using Implements with As Any by replacing it with As LongPtr (which is what the alternate versions do). So many interfaces were in oleexpimp.tlb for this latter reason, and subsequently are not included in tbShellLibImpl as it's not neccessary.

If you find an oleexpimp.tlb interface is not in WinDevLibImpl, you will be able to use the one from WinDevLib , simply make sure As Any is changed to As LongPtr.

tB has announced plans to support [ PreserveSig ] in implemented interfaces in the future; when that happens WinDevLibImpl will be deprecated.

WinDevLib API standards

This was mentioned above, but it's worth going into more detail. In addition to the COM interfaces, WinDevLib has a large selection of common Windows APIs; this is a much larger set than oleexp. WinDevLib and twinBASIC represented the best opportunity there would be to modernize standards... most VB programs are written with ANSI versions of APIs being the default. This is not the case with WinDevLib . With very few exceptions, APIs are Unicode by default-- i.e. they use the W, rather than A, version of APIs e.g. DeleteFile maps to DeleteFileW rather than DeleteFileA. The A and W variants use [tt]String/LongPtr[tt], and in almost all cases, the mapped version uses String with twinBASIC's DeclareWide keyword-- this disables Unicode-ANSI conversion, so you can still use String without StrPtr or any Unicode <-> ANSI conversion. Note this usually only applies to strings passed as input, APIs passing a LPWSTR that's allocated externally will still be LongPtr, as they're not in the same BSTR format as VBx/TB strings.

All APIs are provided, as a minimum, as the explicit W variant, and an untagged version that maps to the W version. Some, but not all, APIs also have an explicit A variant defined that will perform the normal ANSI conversion for compatibility purposes. This is decided on a case by case basis depending on my impression of how much legacy code is around that needs the ANSI version. All new code should use the Unicode versions.

UDTs used by these calls are also supplied in the same manner, the W variant, an untagged variant that's the same as the W version, and in some cases, an A version. UDTs always use LongPtr for strings, even the untagged versions for DeclareWide.

As noted before, an exception to the rule is SendMessage, due to the enourmous volume of existing code expecting SendMessage to map to SendMessageA.

If you have any doubts about which API is being called, twinBASIC will show the full declaration when you hover your cursor over the API in your code.
A note on seeing UDTs where before they were As Any

The best example of this is many APIs, like file APIs, where in traditional VB declarations, you see 'As Any' and in WinDevLib you see e.g. SECURITY_ATTRIBUTES or OVERLAPPED. These are the correct the definitions, but VB6 had no facility to specify 'NULL', which is what they usually would be set to. So the VB6 way was a workaround, where you could pass ByVal 0.

twinBASIC has direct support for passing a null pointer instead of a UDT. You can pass vbNullPtr to these arguments where previously you would have used ByVal 0 on an As Any argument that you've found is now a UDT.

Example:

VB6:

Public Declare Function CreateFileW Lib "kernel32" (ByVal lpFileName As Long, ByVal dwDesiredAccess As Long, ByVal dwShareMode As Long, lpSecurityAttributes As Any, ByVal dwCreationDisposition As Long, ByVal dwFlagsAndAttributes As Long, ByVal hTemplateFile As Long) As Long

hFile = CreateFileW(StrPtr("name"), 0, 0, ByVal 0, ...)

twinBASIC:

Public Declare PtrSafe Function CreateFileW Lib "kernel32" (ByVal lpFileName As LongPtr, ByVal dwDesiredAccess As Long, ByVal dwShareMode As Long, lpSecurityAttributes As SECURITY_ATTRIBUTES, ByVal dwCreationDisposition As Long, ByVal dwFlagsAndAttributes As Long, ByVal hTemplateFile As LongPtr) As LongPtr

hFile = CreateFileW(StrPtr("name"), 0, 0, vbNullPtr, ...)

Project Download
Option 1: This project is published to the twinBASIC Package Manager; you can directly add it to your project via Settings->Library References->Availabble Packages. It will show up in the list automatically, and selecting it will download it from the twinBASIC Package server.

Option 2: This project is also available on GitHub, which includes an Export folder where you can browse the source from your web browser.

(The attachment size limit no longer permits hosting it here)