The ABCs of APIs Lesson 1

This is the first in a series of tutorials for using API calls. It covers the most fundamental

information. Later tutorials will go into more depth.

What is an API Call?

An API call is a function contained in a library file, called a Dynamic Link Library or

DLL. These files have an extension of "*.DLL".

Here is an example of an API call. We can use it to determine if a window or control is enabled or

disabled.

CallDLL #user32, "IsWindowEnabled",_
   hButton as uLong,_   'handle of window or control
   result As Boolean    'nonzero = enabled

Liberty BASIC allows us to enable or disable a window or control, but there is no Liberty BASIC

function to discover if a window or control is currently enabled or disabled. We can get around that

limitation with this handy API function. Here is a Liberty BASIC program that makes use of the

"IsWindowEnabled" API function. Copy it and paste it into Liberty BASIC, then run it to see how it

works.

nomainwin
 
'open a program window
button #1.enable, "Enable/Disable",[doEnable],UL,10,10
button #1.quit, "Quit", [quit], UL, 10, 60
open "API Demo" for window as #1
#1 "trapclose [quit]"
 
'get the handle of the quit button
hButton = HWND(#1.quit)
 
wait
 
[doEnable]
'The IsWindowEnabled function determines whether the
'specified window or control is enabled
'for mouse and keyboard input
 
CallDLL #user32, "IsWindowEnabled",_
   hButton as uLong,_   'handle of window or control
   result As Boolean    'nonzero = enabled
 
'a result of 0 means that the window is NOT enabled
'a nonzero result means that the window IS enabled
 
if result = 0 then
    'if button was disabled, enable it
    #1.quit "!enable"
else
    'if bitton was enabled, disable it
    #1.quit "!disable"
end if
 
wait
 
[quit] close #1 :  end
 

Functions

What is a function? It is a block of code that takes in an argument or a list of arguments and returns

a value. That sounds a little complicated, doesn't it? It's kind of like my bread machine. I put a list

of ingredients into my bread machine, including flour, yeast and water. My bread machine takes these

ingredients and manipulates them, then returns a loaf of fresh-baked bread to me.

The list of ingredients can change. If I put in white flour, my bread machine returns white bread. If I

use rye flour, it returns rye bread. If I use whole wheat flour, it returns wheat bread.

A function accepts a list of ingredients that we call arguments. (They can also be called parameters.)

It manipulates these arguments and returns a value. Liberty BASIC has many built-in functions. Some

examples of native Liberty BASIC functions are MAX(), MIN(), INT(), LEFT$(), MID$()

and VAL().

API calls are functions. We give the API function a list of arguments and it returns a value, which we

store in a variable. API functions are similar to Liberty BASIC's built-in functions, but the syntax is

a little different. API functions are accessed with the CALLDLL statement.

CALLDLL

The parts of the CALLDLL statement are separated by commas. We'll discuss the parts of CALLDLL in

order. The first part of CALLDLL refers to the DLL to be used. Windows contains many DLLs that can be

accessed in Liberty BASIC programs.

The CALLDLL statement first needs to know which DLL is to be used. Many of the DLLs in Windows are

recognized by Liberty BASIC without a need to open them. We refer to them by their handles. A very

common and useful DLL is called "user32.DLL". Liberty BASIC gives us a handle for this DLL. It is

"#user32". The first part of an API call to user32.dll looks like this:

CALLDLL #user32, 

Take note that CALLDLL statements must be on a single line. We often split them into multiple lines

to make them easier to read. We do this by using the underscore line continuation character as we did

in the demonstration program above. It allows us to write a statement of code on multiple lines so that

we can add comments and avoid the need to read long lines of code, but Liberty BASIC still sees the

statement as a single line of code.

Here is an API call on one line of code:

CallDLL #user32, "IsWindowEnabled", hButton as uLong, result As Boolean   

Here is the same API call broken into several lines with the underscore line continuation character.

This allows us to add comments to each argument.

CallDLL #user32, "IsWindowEnabled",_
   hButton as uLong,_   'handle of window or control
   result As Boolean    'nonzero = enabled

API Function Names

The next part of the CALLDLL statement is the name of the API function. It is a text string and it

must be enclosed in quotation marks. The name is case sensitive, so "FunctionName" is not the same as

"FUNCTIONNAME". Be sure to copy the capitalization properly. A generic CALLDLL statement looks like

this:

calldll #dll, "FunctionName",...

An actual API function called "IsWindowEnabled" looks like this:

CallDLL #user32, "IsWindowEnabled",...

API Arguments

Each API call has a set list of arguments separated by commas. Each of these arguments gives the API

function some information. The function evaluates this information. It performs actions and it returns

a value based on the information in these arguments. Arguments can be literal numbers or strings, or

they can be numeric or string variables. They cannot be array elements or expressions.

Arguments are passed "as type". You can read more about types later in this tutorial.

Acceptable arguments that use literal numbers or strings, or numeric or string variables:

calldll #dll, "FunctionName", argument1 as type1,...
calldll #dll, "FunctionName", 23 as type2,...
calldll #dll, "FunctionName", "Some Text" as type3,...
var$ = "A bit of text."
calldll #dll, "FunctionName", var$ as type4,...

Some unacceptable arguments that include expressions and array elements:

calldll #dll, "FunctionName", array(1) as type1,...
calldll #dll, "FunctionName", 23 + 16 as type2,...
calldll #dll, "FunctionName", "Some Text" + "More Text" as type3,...
var$ = "A bit of text."
calldll #dll, "FunctionName", var$ + "hello" as type4,...

Some API functions require many arguments. Arguements are separated by commas. A function with three

arguments looks like this:

calldll #dll, "FunctionName", argument1 as type1, argument2 as type2, argument3 as type3,...

In the demo for this tutorial, there is only one argument. The next tutorial will discuss API functions

that require multiple arguments.

Handles

Many API calls require the Windows handle of a program window or control as one of the

arguments.This Windows handle is a number of type ULONG. It is not the same as the "#handle" Liberty

BASIC handle. We retrieve the Windows handle with the HWND() function and store it in a variable.

In this example, the variable is called "hButton".

button #1.quit, "Quit", [quit], UL, 10, 60
open "API Demo" for window as #1
 
'get the handle of the quit button
hButton = HWND(#1.quit)
 

Types

API functions need to know the type of each argument. Arguments can be numbers, strings or structs.

We will talk about numeric arguments in this tutorial.

The most common numeric types are these. Types that hold numbers that are 4 bytes in size include ulong

and long. Types that hold numbers that are 2 bytes in size include short, ushort, word and boolean.

There are other types, but we won't discuss them in this tutorial.

A CALLDLL statement looks like this with actual types used in the arguments:

calldll #dll, "FunctionName", argument1 as ulong, argument2 as word, argument3 as long,...

Handle Types

In Liberty BASIC, Windows handles must always be passed as either "ulong" type or "word" type. In the

demonstration program at the start of this tutorial, the "hButton" handle is passed "as ulong".

Return Values

API functions return a value, and we must include the "as type" for that value, just as we did for the

list of arguments. The numeric return types include ulong, long, short, word, ushort and boolean.

Here is a generic call that includes the return value. The returned value is always the last part of

the CALLDLL statement and it is separated from the list of arguments by a comma.

calldll #dll, "FunctionName", argument1 as ulong, argument2 as word, result as boolean

Note that you cannot use a variable name for the return type that is called "return" because that is a

Liberty BASIC statement. Variable names cannot be the same as statement or function names in the

Liberty BASIC language. Liberty BASIC programmers often use a variable name of "result" to contain the

value returned by the API function.

Our programs might need to know the value returned by the function so that they can perform the proper

actions. Use "if/then" to manage program flow after an API call has been made, as we've done in the

demonstration program below.

Demo

Here again is the demonstration program. It opens a Liberty BASIC window that contains two buttons. It

retrieves the handle of the Quit button with the HWND() function. It passes that handle into a

user32.dll function called "IsWindowEnabled". The IsWindowEnabled function returns a value telling the

program whether the window or control is enabled at the time the function is called.

The handle is passed as type "ulong". The return type is "boolean". A boolean value is either nonzero

(meaning it is true) or zero (meaning it is false.) If IsWindowEnabled returns a value of 0, the window

is not enabled. If it returns any other value than 0, the window is enabled when the function is

called.

If the quit button is enabled, the program disables it. If it is disabled, the program enables it.

nomainwin
 
'open a program window
button #1.enable, "Enable/Disable",[doEnable],UL,10,10
button #1.quit, "Quit", [quit], UL, 10, 60
open "API Demo" for window as #1
#1 "trapclose [quit]"
 
'get the handle of the quit button
hButton = HWND(#1.quit)
 
wait
 
[doEnable]
'The IsWindowEnabled function determines whether the
'specified window or control is enabled
'for mouse and keyboard input
 
CallDLL #user32, "IsWindowEnabled",_
   hButton as uLong,_   'handle of window or control
   result As Boolean    'nonzero = enabled
 
'a result of 0 means that the window is NOT enabled
'a nonzero result means that the window IS enabled
 
if result = 0 then
    'if button was disabled, enable it
    #1.quit "!enable"
else
    'if bitton was enabled, disable it
    #1.quit "!disable"
end if
 
wait
 
[quit] close #1 :  end
 

---

((ABCs of APIs 2|The next tutorial)) in this series will demonstrate how to use multiple arguments in

an API call to do something we can't do in Liberty BASIC.