Delphi Tutorial: Common Win32 API Data Types.

Many Windows API functions use data types that are specific to the Windows Operating System. These data types are familiar to Windows programmers who have been using APIs for a long time. They will also be reasonably easy to read for the C programmer because they are expressed using the C programming language conventions. They may, however, be unfamiliar to the Delphi programmer who is used to working with Object Pascal.

This tutorial provides a brief look at a number of the Windows API data types, and resolves them to Object Pascal data types.

At the end of this tutorial you will

• Understand some of the common API data types used in most Microsoft APIs
• Be better able to read API function declarations.
• Gain insight into the Win32 API.
• Gain greater insight into the Microsoft Win32 Programmers Reference

We touch on the C programming language in this tutorial. That topic will be covered in much greater detail in the next tutorial: C Primer for Delphi Programmers

Variable declarations in Object Pascal.

In Object Pascal a variable is declared as follows:

Variable : type;

We place the variable name first, and the variable type second. For example:

var I : Integer;

// declare a variable I that holds an integer and allocate memory.

Variable declarations in C

In C the variable type comes first and the variable name comes second. C variable declarations take the form:

type variable;

Some examples of C declaration and the corresponding Object Pascal declaration are:

C Declaration	Pascal	Description
int I;	I : Integer;	/* declare a 32-bit integer variable called I (16-bit in older C implementations)*/
char C;	C : Char;	/* single 8-bit character variable called C */
float F;	F : Real;	/* 32-bit floating point variable called F */
double D;	D : Double;	/* 64-bit floating point variable called D */
Long L;	L : LongInt	/* 32-bit signed integer value */
DWORD dwInfo;	DwInfo : DWORD;	/* a four byte (32-bit) integer used by many Windows functions */

Variable declarations for API functions

The Windows API introduces a number of specific data types used by the Microsoft Windows Operating System. The target audience for most documentation is the C programmer, so variable declarations are expressed using the format customary for the C programming language. They take the form

type variable;

For example, the Win32 API uses the HWND data type to refer to Windows Handles. The HWND data type is simply an unsigned 32-bit integer value that uniquely identifies a Windows Object.

.

The declaration:	HWND : h;	// declare a windows handle
Would look like this in Pascal:	h : Thandle;	// declares a windows handle
Or you could use this:	h : LongWord;	// declares a 32-bit unsigned integer value

In many cases Delphi allows us to directly refer to the data type that is declared in the Microsoft Win32 Programmers Reference. It does this through the use of Type declarations in Windows.pas. HBITMAP is a handle to a Windows Bitmap Object. Windows.pas declares HBITMAP = type LongWord; so you can use the HBITMAP keyword to declare a variable of type HBITMAP.

For:	HBITMAP : h;	// a windows handle to a bitmap
Use:	h : HBITMAP;	// a windows handle to a bitmap
Or you could use:	h : LongWord;	// a 32-bit unsigned integer value

The declaration of h as a LongWord is perfectly valid because the Windows API functions expect a 32-bit unsigned integer value when a bitmap handle is required. For maintenance and compatibility, however, it is generally advisable to use the explicitly stated HBITMAP type.

Common Data Types Used By Windows API Functions.

There are thousands of structures and data types used by Windows API functions and the list keeps growing. The following table lists some of the common Windows Data types as well as one or more corresponding Object Pascal data types.

Windows or C Data Type	Object Pascal Data Type	Comment or Description
ATOM	Word;	An unsigned 16-bit identifier to the global or local atom table for a string. See also Atom.
Bool	LongBool	A four-byte Boolean value
char	Char;	single 8-bit character variable
COLORREF	COLORREF DWORD	A windows color reference value expressed an RGB component. You can also use DWORD for COLORREF
double	Double;	64-bit floating point variable
DWORD	DWORD LongWord Integer	A four byte (32-bit) unsigned integer You can also use LongWord for DWORD. Integer can be used for a DWORD if necessary
FARPROC	Pointer FarProc	A pointer to a procedure. The declaration for the FarProc data type is included in Windows.pas
float	Real;	32-bit floating point variable
HANDLE	THandle	Unsigned 32-bit system handle
HBITMAP	HBITMAP	A windows handle to a Windows bitmap object.
HBRUSH	HBRUSH	A windows handle to a Windows brush object.
HCURSOR	HCURSOR	A windows handle to an Icon (Icons and Cursors are polymorphic)
HDC	HDC	A windows handle to a Device Context.
HENHMETAFILE	HENHMETAFILE	A windows handle to an Enhanced Metafile Object.
HFILE	HFILE	A windows file handle
HINSTANCE	HINST	A windows instance handle used by ShellExecute and ShellExecuteEx
HFONT	HFONT	A windows handle to a logical font
HGDIOBJ	HGDIOBJ	A windows handle to a GDI object.
HGLOBAL	HGLOBAL Thandle	A windows handle that identifies a global windows object. You can also use Thandle for HGLOBAL
HHOOK	HHOOK LongWord	A handle to a windows hook. You can also use LongWord for HHOOK
HICON	HICON	A windows handle to an Icon.
HINST	HINST	A windows handle to an instance object.
HKL	HKL	A windows handle to a keyboard layout
HLOCAL	HLOCAL Thandle	A windows handle that identifies a local windows object. You can also use Thandle for HLOCAL
HMENU	HMENU	A windows handle to a Menu.
HMETAFILE	HMETAFILE	A windows handle to a Metafile
HMODULE	HMODULE	A windows handle to a module
HPALETTE	HPALLETTE	A windows handle to a color palette
HPEN	HPEN	A windows handle to a pen
HRGN	HRGN	A windows handle to a region object
HRSRC	HRSRC	A windows handle to a resource object
HTASK	HTASK	A windows handle to a task
HWND	Thandle	A windows handle. Click here for an example using SHGetSpecialFolderLocation.
int	Integer;	a 32-bit integer variable (16-bit in older C implementations)
LANGID	LANGID Word	Language Identifier You can also use Word
LCID	DWORD LongWord	Locale identifier LongWord can also be used
LCTYPE	LCTYPE LongWord	Locale type constant LongWord can also be used See win32.hlp for more information about LCTYPE constants
long	LongInt	/* 32-bit signed integer value */
long double	Extended	/* 80-bit floating point variable called L */
LPARAM	LPARAM LongInt	A 32-bit message parameter e.g. SendAppMessage Definition included in Windows.pas
LPCSTR	PansiChar;	A pointer to an AnsiChar null terminated string
LPDWORD	^DWord	A pointer to a 32-bit integer (DWord)
LPSTR	PansiChar;	A pointer to an AnsiChar null terminated string.
LPTSTR	PChar	A pointer to a null terminated string
LRESULT	LRESULT LongInt	A 32-bit return value Definition included in Windows.pas
PBOOL	^BOOL	A pointer to a Boolean (true/false) value
PBYTE	^Byte	A pointer to an unsigned 8-bit byte value.
PDOUBLE	^Double	A pointer to a 64-bit floating point value
PDWORD	^DWord	A pointer to a 32-bit integer (DWord)
PHANDLE	^Thandle	A pointer to a windows handle.
PINT	^Integer	A pointer to an integer
PIDL	PItemIDList	A pointer to an item identifier list which provides a method of accessing locations that are not typically accessed through the file system, such as My Computer, Desktop, printers etc. See also SHGETPATHFROMIDLIST
PINTEGER	^Integer	A pointer to a signed 32-bit integer value
PLONGINT	^LongInt	A pointer to a signed 32-bit integer value
PSINGLE	^Single	A pointer to a single-byte floating point real data type
PSMALLINT	^SmallInt	A pointer to a signed 16-bit integer value
PUCHAR	^Byte ^Char	A pointer to an 8-bit character
PUINT	^LongWord	A pointer to an unsigned 32-bit integer
PULONG	^LongWord	A Pointer to an unsigned 32-bit integer value
PWORD	^Word	A pointer to an unsigned 16-bit integer
short	SmallInt	A signed 16-bit integer.
short int	SmallInt;	16-bit integer variable
UCHAR	Byte Char	An 8-bit character
Uint	LongWord	An unsigned 32-bit integer
Ulong	LongWord	An unsigned 32-bit signed integer value
WPARAM	WPARAM LongInt	A 32-bit message parameter e.g. SendAppMessage Definition included in Windows.pas
WPARAM	LongInt	You can also use LongInt for WPARAM

Function declarations in Windows API functions.

Once again, to the Pascal (Delphi) programmer function declarations may appear to be written backwards. They use the C Programming Language Convention and take the form:

return-type function-name(parameter-list,...);

return-type	the variable type that the function returns.
function-name	the name of the function.
parameter-list	the list of parameters that the function takes separated by commas.

The return variable type is specified before the actual function definition.

The C function:	int calcnumb(int n);
Would look like this in Pascal:	Function calcnum(n : Integer) : Integer;

Look at GetLocaleInfo

Now we are ready to look up an API function in Win32.hlp . It tells us the following about the function: GetLocaleInfo

The GetLocaleInfo function retrieves information about a locale.

int GetLocaleInfo(

LCID Locale, // locale identifier

LCTYPE LCType, // type of information

LPTSTR lpLCData, // address of buffer for information

int cchData // size of buffer

);

We can see the following:

• The function returns an integer;
• We can refer to table 1 above to determine the parameters for the function.

Locale : LCID; // locale identifier

LCType : LCTYPE; // type of information we are looking for

LpLCData : Pchar; // pointer to the text buffer (string) that will receive the information

CchData : Integer; // specifies the length of the LplCData buffer

• The function can be expressed in Object Pascal as follows:

function GetLocaleInfo(Locale: LCID;

LCType: LCTYPE;

lpLCData: PChar;

cchData: Integer): Integer; stdcall;

Understand the parameters for GetLocaleInfo

Reviewing the help file tells us that we need to provide certain information:

Locale	Locale identifier which must be LOCALE_SYSTEM_DEFAULT or LOCALE_USER_DEFAULT
LCTYPE	The type of information we are looking for
CchData	the length of the string we have allocated to receive the information
LpLCData.	The information will be placed into this string

The type of information we are looking for must be placed into the LCTYPE variable. Unfortunately Win32.hlp (at least the version I have) does not give us a link to any type of information about exactly what to place here. We need to check the index for LCTYPE.:

• Open Win32.hlp
• Click on the Index tab
• Type LCTYPE
• Open the topic LCTYPE Constants.

Win32.hlp provides us with a list of constants that indicate which information can be retrieved. Some examples are:

LOCALE_SNATIVECTRYNAME	Native name of the country.
LOCALE_IDEFAULTLANGUAGE	Language identifier for the principal language spoken in this locale. This is provided so that partially specified locales can be completed with default values. The maximum number of characters allowed for this string is 5.
LOCALE_IDEFAULTCOUNTRY	Country code for the principal country in this locale. This is provided so that partially specified locales can be completed with default values. The maximum number of characters allowed for this string is 6

We now have enough information to use the function. In the sample program that follows we will use the GetLocaleInfo API function to retrieve the name of the country:

.

The sample 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 a Button on the form and set the properties to:

Name: Button1

Make sure your Unit1 uses clause contains (it will)

Windows.pas

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

procedure TForm1.Button1Click(Sender: TObject);

var

LPLCData : Array[0..48] of Char;

i : Integer;

begin

i := GetLocaleInfo(LOCALE_USER_DEFAULT, LOCALE_SNATIVECTRYNAME, LPLCData, 48);

if i <> 0 then

Label1.Caption := LPLCData

else

Label1.Caption := 'ERROR: The function did not work';

end;

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

We have used the GetLocaleInfo Win32 API function to retrieve the country name from our computer as a string.

Summary

In this tutorial we have learned.

• Using the Win32 API requires the use of Windows Data Types. Borland has made this easier by adding most of the data types to Windows.pas. If no definition for the data type is available, the chart above can also be used as a guide.

• API variable declarations take the form

type variable;

• API function declarations take the form:

return-type function-name ( parameter-list,... );

• The Win32.hlp file gives us most of the information we need, if we are willing to dig a little.

In the next tutorial we will take a closer look at the C programming language.

References

References on your computer.

Delphi 6 online help
WIN32.HLP	The Microsoft Win32 Programmers Reference
Windows.pas	Borland Delphi Run-time Library - Win32 API Interface Unit.
ShlObj.pas	Borland Delphi Run-time Library - Win32 API Shell objects Interface Unit.
CommCtrl.pas	Win32 common controls 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

Beginning Visual C++5 by Ivan Horton, 1997 Wrox Press Ltd. ISBN 1-861000-08-1

Visual C++5 For Dummies by Michael Hyman & Bob Arnson, 1998 IDG Books Worldwide, Inc ISBN 0-7645-0059-7

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

Copyright © 2003 Paul Griffiths, www.jpgriffiths.com.

Last Update

Last Updated: [January 2003]

Home | Tutorials Home