Introduction to the Windows API

1
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 OSs print
  queue (an API call)

2
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

3
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

4
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

5
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).

6
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

7
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 youre really interested
  in using

8
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

9
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

10
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

11
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

12
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. Long A 32-bit
  integer. String A
  variable-length string.

13
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

14
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

15
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

16
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

17
(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

18
Type EXAMPLESTRUCT longvar As Long another As
Long astruct As RECTEnd 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

19
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

20
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

21
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

22
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