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* function contained in a library file, called a *Dynamic Link Library* or *DLL*. DLL . These files have an extension of "*.DLL".

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 manipulated these arguments and returns a value.

Liberty BASIC has many built-in functions. One of them is the *MAX()* MAX() function. It takes in two arguments and it returns a value. The arguments are numbers. The returned value is the larger of the two arguments. In the example below, the returned value is contained in the variable "z". The *MAX()* MAX() function accepts the two arguments, in this example the are the number 7 and the number 2, and it places the larger of those two numbers into the variable "z". Printing z produces "7".

 z = MAX(7,2) 
 print z 

The arguments can be variables. The code using variables in place of literal numbers looks like this:

 x = 7 
 y = 2 
 z = MAX(x,y) 
 print z 

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* CALLDLL statement.

CALLDLL

The *CALLDLL* CALLDLL statement needs to know which DLL is to be used. 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 looks like this:

 CALLDLL #user32, 

That's not all, though! More information follows that statement, and we'll talk about each part in order.

Make note that *CALLDLL* 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. 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.

API Function Names

The next part of the *CALLDLL* 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 "IsIconic" looks like this:

 CallDLL #user32, "IsIconic",... 

API Arguments

Each API call has a set list of arguments that must be passed into the function. Each of these arguments gives the API function some information. The function evaluates this information. 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:

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

Some unacceptable arguments:

 calldll #dll, "FunctionName", array(1) as type1,... 
 calldll #dll, "FunctionName", 23 + 16 as type3,... 
 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. A function with three arguments looks like this:

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

Handles

Many API calls require the Windows handle of a program window 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()* HWND() function and store it in a variable. In this example, the variable is called "hWindow".

 open "A Window" for window as #1 
 
 'get the handle of the Liberty BASIC window 
 hWindow = HWND(#1) 
 

Types

API functions need to know what kind of argument is being passed in. 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, handles must always be passed as either "ulong" type or "word" type.

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. There is a return type of "void" for functions that perform an action, but do not return a value. 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* CALLDLL statement.

 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 users often use a variable name of "result" to contain the value returned by the API function.

Our program often needs to know the value returned by the function so that it can perform the proper actions. Use "if/then" to manage program flow after an API call has been made.

Demo

Here is a small demonstration program. It opens a Liberty BASIC window. It retrieves the handle of the window with the *HWND()* HWND() function. It passes that handle into a user32.dll function called "IsIconic". The IsIconic function returns a value telling the program whether the window whose handle is passed as an argument is minimized 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 IsIconic returns a value of 0, the window is not minimized. If it returns any other value than 0, the window is minimized when the function is called.

 open "A Window" for window as #1 
 #1 "trapclose [quit]" 
 
 'get the handle of the Liberty BASIC window 
 hWindow = HWND(#1) 
 
 'The IsIconic function determines whether the 
 'specified window is minimized (iconic). 
 CallDLL #user32, "IsIconic", hWindow as uLong, result As Boolean 
 
 'a result of 0 means that the window is NOT iconic 
 'a nonzero result means that the window IS iconic 
 
 if result = 0 then 
 print "Window is not minimized." 
 else 
 print "Window is minimized." 
 end if 
 
 wait 
 
 [quit] close #1 : end 

---