Transcript Introduction to the Windows API

Introduction to the Windows API

API - Application Programming Interface

an API is the software interface for
things such as the OS

an API is the fundamental level of
higher-level programming

in high-level programming, a program
has an intermediate to execute tasks

Microsoft Word does not directly control
the printing it puts a print task on the
OS’s print queue (an API call)
Benefits of API Programming


Using API calls in Visual Basic can cut
down on the number of dependency
files and thus the size of the application
package which you need to deploy to
users.
Sometimes now and especially in
previous versions of VB API calls
were the only way to do certain things
like starting and running executable files
to do this now use the FSO File System
Objects in the Scripting Runtime Library
Benefits of API Programming

Designers of software do not have to
worry about the basic chores involved in
every program (such as disk access,
memory allocation, displaying graphics

Every time there is an improvement in
the way hardware is accessed each
program would have to be rewritten to
take advantage of these changes.
API calls are more powerful than VB
methods Powerful meaning can do
more / has more features

API Drawbacks

API functions are significantly more
error-prone

API functions are prone to fail
spectacularly - shut down with a GPF

Visual Basic comes with almost no API
documentation

syntactically challenging for non C++
programmers
Where is the Windows API?

C:\Windows\System directory
Win32 API another term for these DLLs

user32.dll (user interface functions)
most functions we use are in here

kernel32.dll (o.s. kernel functions)

gdi32.dll (graphics device interface
functions)

shell32.dll (Windows shell functions).
Accessing the Microsoft
Windows API

The Windows API contains thousands
of functions, subs, types, and constants
that you can declare and use in your
projects

These procedures are written in the C
language so they must be declared
before you can use them with VB

the easiest way to access the Windows
API is by using the predefined declares
included with Visual Basic
API Viewer Application

API Viewer is a VB Add-In. It uses
Win32api.txt, located in the \Winapi
subdirectory of the main VB directory.
You need to load this file!

The viewer allows you to search
through this text file to put together a
series of dependant function calls.

Sometimes you need to use functions
that get values for the function you’re
really interested in using
Components of the Win API

Functions - provide API functionality

Structures multiple individual variables
passed between functions

Named Constants - numeric codes for
information

Callback Functions defined completely
in your program a way to process each
item found belonging to the group

Messages are sent to objects to tell
them to do something
Declaring the Function

Before an API function can be using in
Visual Basic, it must first be declared

The Declare statement can only
appear in the (declarations) section of
a form or module

If it appears in a form, the declaration
must be Private

In a module, the declaration can be
either Public or Private
[{Public | Private}] Declare Function
function_name Lib "DLL_filename"
[Alias "function_alias"]
(argument_list) As data_type

function_name - safest to make this the
same as the"official" name

DLL_filename - name of the DLL file
which stores the function. This does not
include the path

function_alias almost every function
which has a string as a parameter has
two versions ANSI or Unicode for
[{Public | Private}] Declare Function
function_name Lib "DLL_filename"
[Alias "function_alias"]
(argument_list) As data_type



English speakers use ANSI
ANSI
version ends with the letter A Unicode
version ends with the letter W
argument_list same as VB
data_type the return type
almost always a long
[{ByVal | ByRef}] argument_name
As data_type, ...

argument_name - gives clue as to what
the argument represents can use any
name but best to use “official” name

data type specifies the size and format

Allowed Data types
Byte An 8-bit integer.
Integer A 16-bit integer.
A 32-bit integer.
variable-length string.
Long
String A
ByVal and ByRef

the method used to pass a parameter to
the API function

ByVal This method prevents the
function from altering the contents

ByRef this method passes a sort of
reference to the variable itself

Strings are always passed ByVal
structures are always passed ByRef
Entire Arrays are always passed ByRef
hDC & hWnd
– hWnd Handle A unique 32 bit integer
defined by the operating environment and
used by a program to identify and switch to
an object, such as a form or control.
– hDC device context
similar in appearance to handles
can be the intermediary between your
program and a physical device also
windows themselves are considered to be
devices need hDC to draw (use graphical
methods) on an object
Pointers and Flags

pointer a 32-bit integer variable which
holds a memory address usually the
location of some other object

VB has little support for pointers 99.5%
of the time Visual Basic handles pointer
for you
A flag is simply a type of named
constant. The special thing about flags
is that they can be combined with other
related flags like (shift control alt) mask

Using API Structures

Structures allow a function to receive or
return a large amount of information
without cluttering the argument list

Structures almost always group related
information

To define a structure in Visual Basic, the
Type block is used
[(Public | Private}] Type type_name
member1 As data_type1
member2 As data_type2
...
End Type


type_name The name of the structure
member1, member2, ...
– The name of an individual member of the
structure

data_type1, data_type2, ...
– The data type of a particular item in the
structure
Type EXAMPLESTRUCT
longvar As Long
another As Long
astruct As RECT
End Type

To access a data member of the structure
use the . (period) operator between the
variable name and the member name

notice one of the members is another
structure the RECT angle structure

defined a variable to use the structure

Dim ex As EXAMPLESTRUCT
ex.longvar = 54 ‘ store 54 here
Rect is a predefined structure

If you want to use it you must define it
like this
Type Rect
left As Long
top As Long
right As Long
bottom As Long
End Type

Rect a convenient way to keep the
necessary coordinates of a rectangle
grouped together
Using API Callback Functions

a powerful tool, giving great flexibility to
some API functions

allows your program to build its own
routines to handle events generated by
the API functions themselves

Windows does not define any "default"
callback functions

The most common examples of
callback functions occur in enumeration
Enumeration

During an enumeration, the invoked API
function locates all objects which fit the
desired category

However, the API function does not
know what to do with all the handles it
finds

Callback functions typically process
some data with these handles during
the middle of a API function call
The AddressOf Operator


The only specific pointer in VB
It is a pointer to an address of a
function defined by your program

This function must be Public and be
defined in a module (not a form).

can only be used inside of the
argument list of a call to a function; it
cannot be used any other time