The Xbase++ Programmer
Some basic thoughts on API Programming.

Previous Page

Home
Articles
Source Code
Tools
FAQs
Links

 

The basics of API development are relatively simple.

Create the Win32 Prototype in Xbase++ and then call that Win32 Function in your application.

First, let us simplify things a bit. The "Win32 Protoype" is a fancy phrase that says "explain what to call and what I need to pass to it."

For example, one of the simplest Win32 API functions allows you to lock a workstation programmatically.

      Function: LockWorkStation()
     Prototype: DLLFunction LockWorkStation() USING STDCALL FROM USER32.DLL

The Prototype, above, is then converted in Xbase++ via the Preprocessor to be:
   FUNCTION LockWorkStation()
      LOCAL nDll:=DllLoad("USER32.DLL")
      LOCAL xRet:=DllCall(nDll,32,"LockWorkStation")
      DllUnLoad(nDll)
   RETURN xRet
The FUNCTION code is actually on a single line, but for readability it has been changed to the more common format.

As we can see, an Xbase++ Function has been created with the Win32 Function name.
When called, it loads the appropriate Windows API DLL and then calls the API Function.
The return value is stored in xRet and then the DLL is unloaded from memory.
The function finishes by returning the results to the Xbase++ Application.

Not much mystery here, is there?

There are a couple of very important things to remember.
First, the Windows API is Case-Sensitive.
LockWorkStation() is not the same as lockWorkStation().

Even though in Xbase++ they would be considered identical, using the DLLFunction you must maintain Case-Sensitive standards.

The other thing to remember is that some Win32 API calls are ANSI and Unicode versioned.
When this occurs, simply append an 'A' or 'W' (wide) to the function.

In general, if the Function returns or processes text, it probably has an ANSI and Unicode version.

Ok, so what about passing parameters?
Lets look at the API Function: PostMessageA() ( PostMessageA() or PostMessageW() )

First, notice the 'A'. This is an ANSI function, PostMessageW() is the Unicode.
For our example, we'll use the ANSI version.
  Function: PostMessageA()
 Prototype: PostMessageA( hWnd, wMsg, wParam, lParam )
In our application, it will look like:

DLLFunction PostMessageA( hWnd, Msg, wParam, lParam ) USING STDCALL FROM USER32.DLL

URL: http://msdn.microsoft.com/en-us/library/ms644944.aspx

The documentation in the MSDN Library states:
    PostMessage Function
    The PostMessage function places (posts) a message in the message queue
    associated with the thread that created the specified window and returns
    without waiting for the thread to process the message.
For an explaination of the parameters:
    hWnd    Handle to the window that will receive the message.
    Msg     Specifies the message to be posted.
    wParam  additional message-specific information.
    lParam  additional message-specific information.
In Xbase++, we can get the Windows Handle from the ::GetHWnd() Method.
As far as the message (Msg), it depends on what you are trying to accomplish.

The Data Type is UINT.
UINT is a 32-bit unsigned integer (range: 0 through 4294967295 decimal).

For wParam and lParam, the message you are posting and the window receiving it will determine what to send. In most cases, a NULL can be passed. A NULL is an Chr(0).

How do we convert from Xbase++ Data Types to Windows Data Types?
Xbase++ has some built in functions or we could write our own.

The built in functions are:
API Function Definitions and information:
Conversions from WinAPI values to Xbase++ Values
 Size         Integers
 in Bits  Signed  Unsigned  Float
  8               ASC
 16       Bin2I   Bin2W
 32       Bin2L   Bin2U
 64                          Bin2f()  - Converts a 64 bit IEEE floating point
                                        number to a numeric value.
Bin2I has a complementary function I2Bin as does Bin2W, Bin2L and Bin2U.

Xbase numeric to API numeric, I2Bin(). To convert API values back to Xbase++ numerics, use the compliment function Bin2I(). This is the same with the other Bin2?() functions.
Numeric to API:
      I2Bin
      W2Bin
      L2Bin
      U2Bin
API to Numeric:
      Bin2I
      Bin2W
      Bin2L
      Bin2U

For 8 bit values, you can use Chr() and ASC().

The MSDN Documentation of Win32 and COM development has a wealth of functions to choose from. For more information on functions you canl use, see MSDN Site at;

http://msdn.microsoft.com/en-us/library/aa139672.aspx

You can find just about any Win32 function exposed by the Operating System.

 

 

 
Helping you get more out of the Xbase++ language.
For more information or to contribute, please contact: Support@XbaseProgammer.com