Delphi API Tutorial: Finding and understanding the Microsoft WIN32 Programmers Reference

Delphi ships with a copy of the Microsoft Win32 Programmers Reference as a Help File. It provides information about the thousands of available Win32 API functions. Understanding the reference can be difficult for Delphi programmers because it is intended for the C programmer. This document will (hopefully) help you to find and understand the Win32 Programmers Reference.

In this tutorial we will work with an API function called GlobalMemoryStatus. We will look at the function declaration in the Microsoft Win32 Programmers Reference, find the Object Pascal declaration and construct a program that uses the API. If you are not familiar with the concept of the API functions see Introducing the Win32 API for Delphi Programmers.

At the end of this tutorial, you will know

Where to find the Microsoft WIN32 Programmers Reference
How to look up an API function declaration
How to find the Object Pascal version of the function declaration using the Delphi Run Time Library.
How to find the Object Pascal version of an API structure
How to incorporate an API function into your own Delphi program or component
Where to look for additional information about the WIN32 API functions

Finding the Microsoft WIN32 Programmers Reference on your computer.

Delphi ships with a copy of a help file called WIN32.HLP. By default it is installed to C:\Program Files\Common Files\Borland Shared\MSHelp. This help file is the Microsoft Win32 Programmers Reference. Open this help file and you have the Programmers Reference right on your computer.

The Win32 Programmers Reference is a reference file, not a how to book. Thousands of API functions are documented but there are few examples and there is, to the best of my knowledge, not a single example written in Object Pascal. Fortunately there are plenty of examples out there waiting to be found and incorporated into your program. See references for more information.

Using the Microsoft Win32 Programmers Reference.

Lets take a look in the Win32 Programmers Reference at the GlobalMemoryStatus function.

Open WIN32.HLP
Click on the Index Tab
Type GlobalMemoryStatus
Click on GlobalMemoryStatus in the index entry list
Click Display

If you did this correctly you will see the declaration for the GlobalMemoryStatus API function.

VOID GlobalMemoryStatus(

LPMEMORYSTATUS lpBuffer // pointer to the memory status structure

);

The declaration is written using the C programming language conventions. You do not have to use C to call the API function. Indeed you do not even have to know much about the C. Of course an understanding of the C language can go a long way towards better understanding the API and you may find A C Primer for Delphi Programmers helpful.

Using the Delphi Run Time Library

The folks at Borland did not ignore the need to declare all those functions, variables and structures used by the Windows API. They provided a complete run time library as a series of Delphi Units (.pas) files that provide most of the information needed. On my computer they were installed automatically when I installed Delphi 6 into:

C:\Program Files\Borland\Delphi6\Source\Rtl\Win

Inside this folder you will find a number of Delphi Units that can help sort out all those API calls and variables. For a partial list see the references section at the end of this document.

The most commonly used unit is Windows.pas. In this tutorial we will use windows.pas to find out about GlobalMemoryStatus.

Use Windows.pas to obtain the Object Pascal Declaration

Take a look in Windows.pas. It should be located in your Delphi source folder (something like C:\Program Files\Borland\Delphi6\Source\Rtl\Win\Windows.pas. The unit should be opened with Delphi. However, you can use Notepad, WordPad, or any other program capable of reading a text document.

Find GlobalMemoryStatus and take a look at what Borland has given us.

procedure GlobalMemoryStatus(var lpBuffer: TMemoryStatus); stdcall;

Understanding the parameter.

We now have the Object Pascal declaration for the GlobalMemoryStatus procedure and can see that it requires a pointer to a TMemoryStatus parameter. Lets find out something about TMemoryStatus.

Open Win32.hlp again and open the help information for GlobalMemoryStatus.

Click the link for MEMORYSTATUS and the following information will be displayed:

typedef struct _MEMORYSTATUS { // mst

DWORD dwLength; // sizeof(MEMORYSTATUS)

DWORD dwMemoryLoad; // percent of memory in use

DWORD dwTotalPhys; // bytes of physical memory

DWORD dwAvailPhys; // free physical memory bytes

DWORD dwTotalPageFile; // bytes of paging file

DWORD dwAvailPageFile; // free bytes of paging file

DWORD dwTotalVirtual; // user bytes of address space

DWORD dwAvailVirtual; // free user bytes

} MEMORYSTATUS, *LPMEMORYSTATUS;

This is the structure definition for MEMORYSTATUS structure. A C structure is like an Object Pascal record.

In Windows.pas go to the top of the file and search for MemoryStatus. The Borland folks have given us a record type that can be used whenever a MEMORYSTATUS structure is needed.

type

PMemoryStatus = ^TMemoryStatus;

_MEMORYSTATUS = record

dwLength: DWORD;

dwMemoryLoad: DWORD;

dwTotalPhys: DWORD;

dwAvailPhys: DWORD;

dwTotalPageFile: DWORD;

dwAvailPageFile: DWORD;

dwTotalVirtual: DWORD;

dwAvailVirtual: DWORD;

end;

A DWORD is simply an integer. This record consists of 8 integer values.

Sizeof matters

You may have noticed that the help file says: “Before calling this function, the calling process should set the dwLength member of this structure.” API functions often require us to pass the size of the structure (record) that we are passing to it as a parameter. In other words, even though the API gave us the structure, it still wants us to tell it how big it is.

The best way to do this is to use Delphi’s SizeOf function. The syntax for the SizeOf function is:

function SizeOf(structure): Integer;

Therefore we would need to add something like the following to our program before calling the GlobalMemoryStatus function.

MemoryStatus.dwLength := SizeOf(MemoryStatus);

The program.

Create a new application by choosing New from Delphi’s File menu and choosing Application.

Drop a Label component on the form and set the properties as follows

Name: Label1

Autosize: True

Drop another Label component on the form and set the properties as follows

Name: Label2

Autosize: True

Drop a Button on the form and set the properties to:

Name: Button1

Make sure your Unit1 uses clause contains:

Windows.pas // windows.pas should be included by default

Add the following code to the On Click Event handler for Button1

procedure TForm1.Button1Click(Sender: TObject);

var MemoryStatus : TMemoryStatus;

begin

MemoryStatus.dwLength := SizeOf(MemoryStatus);

GlobalMemoryStatus(MemoryStatus);

Label1.Caption := 'Physical Memory: ' + IntToStr(MemoryStatus.dwTotalPhys);

Label2.Caption := 'Virtual Memory: ' + IntToStr(MemoryStatus.dwTotalPageFile);

end;

Run your program and click Button1. The results should look something like this.

Summary

The WIN32.HLP file gives us the C declaration for the Win32 API functions and an explanation.
Windows.pas and other files in the Delphi/source/rtl folder contain the Object Pascal version of the declarations and structures used in the API.
The combination of the two to gain enough information to use the API.
There are many additional resources available to us to help us understand the information available in WIN32.HLP.

References

References on your computer.

Delphi 6 online help
WIN32.HLP	The Microsoft Win32 Programmers Reference
Acl.pas	Borland Delphi Run-time Library - Access Control List (security) API functions, types and constants.
ActiveX.pas	Borland Delphi Run-time Library - ActiveX / OLE 2 Interface
CommCtrl.pas	Borland Delphi Run-time Library - Win32 common controls interface unit
Mapi.pas	Borland Delphi Run-time Library - Messaging Applications Programming Interface
ShellAPI.pas	Borland Delphi Run-time Library - Win32 Shell API Interface Unit
ShlObj.pas	Borland Delphi Run-time Library - Win32 API Shell objects Interface Unit.
Windows.pas	Borland Delphi Run-time Library - Win32 API Interface Unit.
Winsock.pas	Borland Delphi Run-time Library - Win32 sockets API Interface Unit
WinSvc.pas	Borland Delphi Run-time Library - Win32 service API interface unit

Internet

Other tutorials	Other tutorials in this series
The Jedi Code Library	An excellent cooperative effort among Delphi programmers with lots of free source code
The MER System Database Search	A free newsgroup search engine you can use to find Delphi newsgroup postings
Microsoft Developers Network	The Microsoft support site for developers
Borland Developers Network	Borland’s support site.
Newsgroups	Borland Delphi newsgroups.

Books

The Tomes of Delphi: Win32 Core API - Windows 2000 Edition by John Ayers, ISBN 1-55622-750-7 Wordware Publishing Inc

The Tomes of Delphi: Win32 Shell API – Windows 2000 Edition by John Ayers, ISBN 1-55622-749-3 Wordware Publishing Inc

Windows 2000 SYSTEMS PROGRAMMING Black Book by Al Williams, 2000, ISBN 1-57610-280-7, The Coriolis Group

Misc.

Use of Source Code

The source code contained in this tutorial is provided free of charge, AS IS WITHOUT WARRANTY OF ANY KIND AND IS PROVIDED WITHOUT ANY IMPLIED WARRANTY OF FITNESS FOR PURPOSE OR MERCHANTABILITY. You may incorporate this source code into your own program but you do so at your own risk. Please remember to test your program and any source code copied from this site. Please report errors and improvements to jpgriffiths.com.

Copyright

Last Update

Last Updated: [January 2003]

Home | Tutorials Home