The Basic Cockpit Idea

The wrong Approach

The final goal of bringing the complete Windows API to Xbase++ soon makes you realize that you cannot start digging into details right from the start. There are already lots of tools floating in the Xbase++ world that cover some Windows API areas, but even they don't conform to a common standard. Xbase++'s lack of basic functionality like structures and callbacks generally puts a natural limit to the extent of these tool collections. Many of the functions are completely unusable because Xbase++ puts its own, incompatible layer of abstraction over them. (GUI, GDI)

Some of the available libraries put their own level of abstraction on top of the plain Windows API. However, these abstractions don't actually contribute to the compatibility of the tools between one another.

So the task at hand is not to create another great tool collection that comes with a new set of abstractions and fantastic enhancements to what the O/S has to offer, but to standardize the way the API functions are brought into the Xbase++ world. Wouldn't it be great to find the function you need in the MSDN documentation and have it available in Xbase++ in a few minutes of time, if it isn't available already? And wouldn't it be great to share the newly available function with everyone else using Xbase++ and Cockpit? But how can we achieve this vision?

The simple answer is: Standardization

Manually coded Wrappers? - Yikes!

Calling a Dll function from Xbase++ isn't a big deal, as long as simple parameters are involved. If it gets a little more complicated, BAP will help. But BAP won't help when things go beyond simple structures (which still have to be assembled and dissected by hand) and a single callback per thread.

That's where Cockpit comes into the game. It allows you to define advanced parameter conversions for calls to dll functions. However, Cockpit does not redefine the Xbase++ way of parameter passing, it just comes with additional adaptions. For example you can pass structures or objects to dll functions and you can also receive them.

These parameter adaptions are specified in a source file that is translated with the Xbase++ preprocessor into a module that imports the dll functions and makes them available as Xbase++ functions which internally take care of the necessary parameter conversions. All functions of a dll are listed in one source file. Cockpit, its generator files and the Xbase++ preprocessor take care of the rest.

Once you have understood the supported adaptions, a glance at the MSDN documentation and maybe another crosscheck glance at the Cockpit import definition (for complicated calls) will enable you to use any Windows API function. And if a function is not available, you write one line of code defining the newly imported function and it's available for you. In some cases you'll have some other stuff to do, like defining the necessary structures, but very often that's just "intelligent copying" of code from the .h files to your own structure definition .prg files.

What you receive for free

The newly imported function will automatically be able to receive (and return) other already existing Cockpit structures, objects, interfaces, ... as parameters and will hence smoothly integrate with other code created by fellow programmers using Cockpit.

This level of interoperability comes at a price: No abstraction allowed. The moment you put a level of abstraction on top of the native API way of doing things, you're on your own. I'm not telling you not to abstract, but you should think twice before you go for it. And maybe you won't need it because Cockpit already comes with an extra level of abstraction, namely object orientation.

Cockpit's object orientation is nothing but bringing all operations available for an O/S object together as methods in one Xbase++ object. In almost all O/S objects Cockpit provides there is only one single instance variable: handle.