Win32 API Programming with Visual Basic

Page 118
  7. System Information Functions  
   
  Let us put some of what we have learned to immediate practice. One of the areas of the Win32 API that we can use profitably even without knowing much about how Windows itself works is the area devoted to system information.  
   
  There are several API functions that can be used to gather information about the computer upon which the functions are running. The Win32 System Information functions are listed in Table 7-1.  
   
  Table 7-1. System Information Functions  
   
  GetComputerName  
   
  GetSystemMetrics  
   
  GetWindowsDirectory  
   
  GetKeyboardType  
   
  GetTempPath  
   
  SetComputerName  
   
  GetSysColor  
 
   
  GetUserNameSesSysColors  
   
  GetSystemDirectory  
   
  GetVersion  
   
  SystemParametersInfo  
   
  GetSystemInfo  
   
  GetVersionEx  
 

   
  Let us look at a few of these functions.  
 
  The Computer's Name  
   
  The GetComputerName function is used to get the current computer's name. The corresponding SetComputerName will set the computer's name. The VC++ declaration is:  
 
  BOOL GetComputerName(

   LPTSTR lpBuffer,    // address of name buffer

   LPDWORD nSize      // address of size of name buffer

);

  
Page 119
   
  Here the parameters are an LPSTR and a pointer to a DWORD, and the return type is BOOL. A corresponding VB declaration is:  
 
  Declare Function GetComputerName Lib "kernel32" Alias "GetComputerNameA" ( _

   ByVal lpBuffer As String, _

   nSize As Long _

) As Long

  
   
  According to the documentation, under Windows 9x the GetComputerName function will fail if the input size is less than the constant MAX_COMPUTERNAME_LENGTH + 1. This constant is defined in WINBASE.H as:  
 
  #define MAX_COMPUTERNAME_LENGTH 15  
   
  which in VB becomes:  
 
  Public Const MAX_COMPUTERNAME_LENGTH = 15  
   
  We can now write a small function to return the computer's name:  
 
  Public Function GetTheComputerName As String

Dim s As String

s = String(MAX_COMPUTERNAME_LENGTH + 1, 0)

lng = GetComputerName(s, MAX_COMPUTERNAME_LENGTH)

GetComputerName = Trim0(s)

End Function

  
   
  (Recall that Trim0 is a simple function to trim a string at the first null.) On my system, the return value is:  
 
  SRCOMPUTER  
 
  Special Windows Paths  
   
  The GetWindowsDirectory, GetSystemDirectory, and GetTempPath retrieve the path to the Windows, Windows System, and Windows temporary files directories. The functions are defined as follows:  
 
  UINT GetSystemDirectory(

   LPTSTR lpBuffer,     // address of buffer for system directory

   UINT uSize           // size of directory buffer

);

UINT GetWindowsDirectory( _

   LPTSTR lpBuffer,     // address of buffer for Windows directory

   UINT uSize           // size of directory buffer

);

DWORD GetTempPath(

   DWORD nBufferLength // size, in characters, of the buffer

 

  

Page 120
 
     LPTSTR lpBuffer     // pointer to buffer for temp path

);

  
   
  The VB declarations are:  
 
  Declare Function GetSystemDirectory Lib "kernel32" Alias "GetSystemDirectoryA" ( _

   ByVal lpBuffer As String, _

   ByVal nSize As Long _

) As Long

Declare Function GetWindowsDirectory Lib "kernel32" _

Alias "GetWindowsDirectoryA" ( _

   ByVal lpBuffer As String, _

   ByVal nSize As Long _

) As Long

Declare Function GetTempPath Lib "kernel32" Alias "GetTempPathA" ( _

   ByVal nBufferLength As Long, _

   ByVal lpBuffer As String _

) As Long

  
   
  Each of these functions returns the number of characters placed in the string buffer. The size of the buffers should be set one larger than the symbolic constant:  
 
  Public Const MAX_PATH = 260  
   
  Here is some sample code:  
 
  Dim s As String, lng As Long

s = String(MAX_PATH + 1, 0)

lng = GetWindowsDirectory(s, MAX_PATH)

Debug.Print Left$(s, lng)

lng=GetSystemDirectory(s, MAX_PATH)

Debug.Print Left$(s, lng)

lng = GetTempPath(MAX_PATH, s)

Debug.Print Left$(s, lng)

  
   
  On my system, the output is:  
 
  C:\WINNT

C:\WINNT\System32

C:\TEMP\

  
   
  Note that, in each case, the documentation says that the return value is the number of characters copied to the buffer, not including the terminating null. This is why we can use the Left$ function to extract just the return string. On the other hand, the documentation for GetComputerName simply says that the return value in nonzero on success, so we used the Trim0 function instead.  
Page 121
 
  The Operating System Version  
   
  The GetVersionEx function returns version information about the Windows operating system and can be used to determine whether the system is running Windows 95, Windows 98, or Windows NT. The declaration is:  
 
  BOOL GetVersionEx(

   LPOSVERSIONINFO lpVersionInformation   // pointer to version info structure

);

  
   
  where lpVersionInformation is a pointer to an OSVERSIONINFO structure, which is defined as follows:  
 
  typedef struct_OSVERSIONINFO{

   DWORD dwOSVersionInfoSize;

   DWORD dwMajorVersion;

   DWORD dwMinorVersion;

   DWORD dwBuildNumber;

   DWORD dwPlatformId;

   TCHAR szCSDVersion[ 128 ];

} OSVERSIONINFO;

  
   
  The documentation for this structure is as follows:  
 
  dwOSVersionInfoSize

Specifies the size, in bytes, of the OSVERSIONINFO structure. This is a common requirement in structures. Since a DWORD is a 4-byte unsigned long and since VB will translate the 128-character string into a 128-byte ANSI character array, the total size is 4*5+128=148.This is also the value returned by the Len function, but not the LenB function, which doesn't take into account the Unicode-to-ANSI translation

  
 
  dwMajorVersion

Indicates the major version number of the operating system. For example, for Windows NT Version 3.51, the major version number is 3. For Windows NT 4. 0 and Windows 9x, the major version number is 4.

  
 
  dwMinorVersion

Indicates the minor version number of the operating system. For example, for Windows NT Version 3.51, the minor version number is 51. For Windows NT 4.0, the minor version number is 0. For Windows 95, the minor version number is 0. For Windows 98, the minor version number is 10.

  
 
  dwBuildNumber

Indicates the build number of the operating system under Windows NT. For Windows 9x, the low-order word contains the build number of the operating system, and the high-order word contains the major and minor version numbers.

  
Page 122
 
  dwPlatformId

Identifies the operating system platform, and can be one of the following values:

  
 
  VER_PLATFORM_WIN32s (= 0)

Win32s running on Windows 3.1

  
 
  VER_PLATFORM_WIN32_WINDOWS (= 1)

Win32 running on Windows 95 or Windows 98

  
 
  VER_PLATFORM_WIN32_NT (= 2)

Win32 running on Windows NT

  
 
  szCSDVersion

For Windows NT, contains a null-terminated string, such as ''Service Pack 3," that indicates the latest Service Pack installed on the system. If no Service Pack has been installed, the string is empty. For Windows 95, this string contains a null-terminated string that provides arbitrary additional information about the operating system.

  
   
  Translating the GetVersionEx declaration into VB gives:  
 
  Declare Function GetVersionEx Lib "kernel32" Alias "GetVersionExA" ( _

   lpVersionInformation As OSVERSIONINFO _

) As Long

  
   
  The intention here is to pass the address of an OSVERSIONINFO structure by reference.  
   
  To translate the structure definition, we replace the DWORDs with Longs, and the TCHAR array, being fixed length, with either a fixed-length string or a byte array. In the former case, VB will do the usual Unicode-to-ANSI translation, but that's fine:  
 
  Type OSVERSIONINFO

   dwOSVersionInfoSize As Long

   dwMajorVersion As Long

   dwMinorVersion As Long

   dwBuildNumber As Long

   dwPlatformId As Long

   szCSDVersion As String * 128 ' 128 characters

End Type

  
   
  Let's give this a try:  
 
  Public Sub PrintVersionInfo

Dim lret As Long

Dim osverinfo As OSVERSIONINFO

osverinfo.dwOSVersionInfoSize = Len(osverinfo)

lret = GetVersionEx(osverinfo)

If lret = 0 Then

   RaiseApiError lret

 

  

Page 123
 
  Else

   Debug.Print "Version: " & osverinfo.dwMajorVersion & "." _

      & osverinfo.dwMinorVersion

   Debug.Print "Build: " & osverinfo.dwBuildNumber

   Debug.Print "Platform ID: " & osverinfo.dwPlatformId

   Debug.Print "String: " & osverinfo.szCSDVersion

End If

End Sub

  
   
  (You will find the RaiseAPIError function defined at the end of Chapter 3, API Declarations.) The output on my system is:  
 
  Version: 4.0

Build: 1381

Platform ID: 2

String: Service Pack 3

  
   
  Here is a short function that returns the name of the operating system:  
 
  Public Function GetOSVersion() As String

' Return name of operating system

Dim lret As Long

Dim osverinfo As OSVERSIONINFO

osverinfo.dwOSVersionInfoSize = Len(osverinfo)

lret = GetVersionEx(osverinfo)

If lret = 0 Then

   GetOSVersion = "unknown"

Else

   Select Case osverinfo.dwPlatformId & "/" & osverinfo.dwMajorVersion

 & "/" & osverinfo.dwMinorVersion

      Case "1/4/0"

         GetOSVersion = "Win95"

      Case "1/4/10"

         GetOSVersion = "Win98"

      Case "2/3/51"

         GetOSVersion = "WinNT351"

      Case "2/4/0"

         GetOSVersion = "WinNT4"

   End Select

End If

End Function

  
 
  System Metrics  
   
  The GetSystemMetrics function retrieves metric (measurement) information about the system. The VC++ declaration is simply as follows.  
Page 124
 
  int GetSystemMetrics(

   int nIndex    // system metric or configuration setting to retrieve

);

  
   
  This translates into VB as:  
 
  Declare Function GetSystemMetrics Lib "user32" ( _

   ByVal nIndex As Long _

) As Long

  
   
  The nIndex parameter is set to one of 49 different possible constants. The requested measurement (generally in pixels or nondimensional units) is returned by the function.  
   
  To give you an idea of the type of information returned, here is a sampling of the constants for this function. All height and width measurements are in pixels:  

Const SM_CMOUSEBUTTONS = 43 ' Number of mouse buttons Const SM_MOUSEWHEELPRESENT = 75 ' True if mouse wheel present ' (Win NT 4 or Win 98 only) Const SM_SWAPBUTTON = 23 ' True if mouse buttons swapped Const SM_CXBORDER = 5 ' Width and height of a window border Const SM_CYBORDER = 6 Const SM_CXSCREEN = 0 ' Width and height of screen Const SM_CYSCREEN = 1 Const SM_CXFULLSCREEN = 16 ' Width and height of client area for a Const SM_CYFULLSCREEN = 17 ' full-screen window Const SM_CXHTUMB = 10 ' Width of the thumb box in a horizontal ' scroll bar. Const SM_CXICONSPACING = 38 ' Dimensions of a grid cell for items in Const SM_CYICONSPACING = 39 ' large icon view. Const SM_CYCAPTION = 4 ' Height of a normal caption area.

 
  System Parameters  
   
  The SystemParametersInfo function is a powerful function for getting or setting system-wide parameters. The function can also update the user profile while setting a parameter. The declaration is:  
 
  BOOL SystemParametersInfo(

   UINT uiAction, // system parameter to query or set

   UINT uiParam,  // depends on action to be taken

   PVOID pvParam, // depends on action to be taken

   UINT fWinIni   // user profile update flag

);

  
Page 125
   
  which can be translated into VB as:  
 
  Declare Function SystemParametersInfo Lib "user32" _

Alias "SystemParametersInfoA" ( _

   ByVal uiAction As Long, _

   ByVal uiParam As Long, _

   pvParam As Any, _

   ByVal fWinIni As Long _

) As Long

  
   
  Note that, for type safety, we can alter the data type of the pvParam depending upon the action to be taken.  
   
  This powerful function can take at least 90 different uiAction values. We will content ourselves with a single example. Note that the function returns a nonzero value on success and 0 on failure. It will set GetLastError, so we can use VB's Err.LastDLLError value.  
   
  System Icon Metrics  
   
  We can get or set the characteristics of system icons (such as those that appear on the desktop) using the constants  
 
  Public Const SPI_GETICONMETRICS = 45

Public Const SPI_SETICONMETRICS = 46

  
   
  For SPI_GETICONMETRICS, the documentation says that the parameter pvParam must point to an ICONMETRICS structure that receives the information. For SPI_SETICONMETRICS, the parameter pvParam must point to an ICONMETRICS structure that contains the new parameters.  
   
  In both cases, we must also set the cbSize member of the ICONMETRICS structure (see the following) and the uiParam parameter of SystemParametersInfo to the size, in bytes, of the structure.  
   
  The ICONMETRICS structure has declaration:  

typedef struct tagICONMETRICS { UINT cbSize; int iHorzSpacing; int iVertSpacing; int iTitleWrap; LOGFONT lfFont; } ICONMETRICS, FAR **LPICONMETRICS;

   
  and the LOGFONT structure is:  
 
  typedef struct tagLOGFONT { // lf

   LONG lfHeight;

   LONG lfWidth;

   LONG lfEscapement;

   LONG lfOrientation;

 

  

Page 126
 
     LONG lfWeight;

   BYTE lfItalic;

   BYTE lfUnderline;

   BYTE lfStrikeOut;

   BYTE lfCharSet;

   BYTE lfOutPrecision;

   BYTE lfClipPrecision;

   BYTE lfQuality;

   BYTE lfPitchAndFamily;

   TCHAR lfFaceName[LF_FACESIZE];

} LOGFONT;

  
   
  where:  
 
  Public Const LF_FACESIZE = 32  
   
  There is an important point to note here. Very often one structure will contain pointers to other structures. In this case, however, the lfFont variable is not a pointer it is the actual structure. Thus, we must combine the two structures when creating a VB version:  
 
  Public Type ICONMETRICS

   cbSize As Long

   iHorzSpacing As Long

   iVertSpacing As Long

   iTitleWrap As Long

   lfHeight As Long

   lfWidth As Long

   lfEscapement As Long

   lfOrientation As Long

   lfWeight As Long

   lfItalic As Byte

   lfUnderline As Byte

   lfStrikeOut As Byte

   lfCharSet As Byte

   lfOutPrecision As Byte

   lfClipPrecision As Byte

   lfQuality As Byte

   lfPitchAndFamily As Byte

   lfFaceName As String * LF_FACESIZE

End Type

  
   
  Note that this structure behaves well with respect to member alignment. (I'll bet you forgot to check that!) We could have used a byte array for lfFaceName as well as a fixed-length string. A fixed-length string is easier to use when outputting the return value, however.  
   
  Here is some code that uses this function:  
 
  Public Sub PrintIconMetrics

Dim im As ICONMETRICS

im.cbSize = Len(im)

lret = SystemParametersInfo(SPI_GETICONMETRICS, Len(im), im, 0&

 

  

Page 127
 
  If lret = 0 Then

   RaiseApiError Err.LastDllError

Else

   Debug.Print "Hor Spacing:" & im.iHorzSpacing

   Debug.Print "Vert Spacing:" & im.iVertSpacing

   Debug.Print im.lfFaceName & "/"

End If

End Sub

  
   
  The output on my system is:  
 
  Hor Spacing:101

Vert Spacing:109

MS Sans Serif

  
 
  System Colors  
   
  The functions GetSysColor and SetSysColors are used to get and set colors for various system elements, such as buttons, title bars, and so on. These items can also be set by the user through the Display applet in the Control Panel.  
   
  The declaration of GetSysColor is simple:  
 
  DWORD GetSysColor(

   int nIndex    // display element

);

  
   
  where nIndex can be set to one of many symbolic constants, for example:  
 
  #define COLOR_ACTIVECAPTION 2  
   
  In VB this becomes:  
 
  Declare Function GetSysColor Lib "user32" (ByVal nIndex As Long) As Long

Public Const COLOR_ACTIVECAPTION = 2

  
   
  The return value is the RGB color. In particular, each color gets a byte in the returned unsigned long: red is the least significant byte, green is next, followed by blue. The high-order byte is 0. (These color bytes appear in reverse order in the long because when it is stored in memory, the bytes are reversed.)  
   
  The SetSysColors function is:  

BOOL WINAPI SetSysColors( int cElements, // number of elements to change CONST INT *lpaElements, // address of array of elements CONST COLORREF *lpaRgbValues // address of array of RGB values );

   
  Here, cElements specifies the number of system elements whose color we want to change, lpaElements is a pointer to a VC++ integer array that contains the indices of elements to change, and lpaRgbValues points to a VC++ integer array of new RGB color values.  
Page 128
   
  The VB version is:  
 
  Declare Function SetSysColors Lib "user32" ( _

   ByVal nChanges As Long, _

   lpSysColor As Long, _

   lpColorValues As Long _

) As Long

  
   
  where we must call the function by specifying the first array element for each array parameter.  
   
  Note finally that both functions return 0 on success and set GetLastError.  
   
  The following example will flash the active title bar between its default color and red every 0.5 seconds, finally leaving the title bar in its original state:  
 
  Public Function FlashTitleBarColor()

Dim i As Integer

Dim lret As Long

Dim SaveColor As Long

Dim lIndices(0 To 0) As Long

Dim lNewColors(0 To 0) As Long

' Get and save current color

SaveColor = GetSysColor(COLOR_ACTIVECAPTION)

Debug.Print "Current color:" & Hex(SaveColor)

For i = 1 To 5

   ' Change to red

   lIndices(0) = COLOR_ACTIVECAPTION

   lNewColors(0) = &HFF

   lret = SetSysColors(1&, lIndices(0), lNewColors(0))

   If lret = 0 Then

      RaiseApiError Err.LastDllError

   End If

   Delay 0.5

   ' Restore original color

   lIndices(0) = COLOR_ACTIVECAPTION

   lNewColors(0) = SaveColor

   lret = SetSysColors(1&, lIndices(0), lNewColors(0))

   If lret = 0 Then

      RaiseApiError Err.LastDllError

   End If

   Delay 0.5

Next

End Function

  
Page 129
   
  The Delay utility is just:  
 
  Sub Delay(rTime As Single)

'Delay rTime seconds (min=.01, max=300)

Dim OldTime As Variant

'Safty net

If rTime < 0.01 Or rTime > 300 Then rTime = 1

OldTime = Timer

Do

    DoEvents

Loop Until Timer - OldTime >=rTime

End Sub
Related

Категории