Windows API Guide: SHUpdateRecycleBinIcon Function


Declare Function VerQueryValue Lib "version.dll" Alias "VerQueryValueA" (pBlock As Any, ByVal lpSubBlock As String, lplpBuffer As Long, puLen As Long) As Long

Platforms

  • Windows 95: Supported.
  • Windows 98: Supported.
  • Windows NT: Requires Windows NT 3.1 or later.
  • Windows 2000: Supported.
  • Windows CE: Not Supported.

Description & Usage

VerQueryValue extracts information from a version information resource. This resource stores version-related information about a 32-bit executable-type file. The GetFileVersionInfo function obtains this resource from the desired file. VerQueryValue can get both general version information and version identifying strings from the resource. Naturally, since version information resources do not exist for non-32-bit applications, nor for non-executable files, this function will not work with them.

Return Value

If successful, the function returns a non-zero value. If an error occured, the function returns 0.

Visual Basic-Specific Issues

To actually use the information retrieved by VerQueryValue, you have to copy the data identified by the pointer lplpBuffer into the appropriate object. To do this, use lstrcpy for strings and CopyMemory for anything else. For the root block, copy the pointer's data into a VS_FIXEDFILEINFO structure. For the code page and language data, copy the data into a four-element Byte array. For version information strings, copy the data into, you guessed it, a string.

If you're a bit confused or overwhelmed, don't be. The example on this page illustrates how to do all three.

Parameters

pBlock
The byte array or similar object that holds the version information resource extracted from a file. To obtain such a block, use GetFileVersionInfo.
lpSubBlock
One of the following strings specifying what information to extract from the resource. A pointer to the extracted information is placed into lplpBuffer.
"\"
Extract the root block of version information, which is in the form of a VS_FIXEDFILEINFO structure.
"\VarFileInfo\Translation"
Extract the identifier of the language and code page in which the version information strings are encoded. While this is not useful in and of itself, this data is necessary to read any version information strings in the resource. See Note 1 below for details about how to use this value.
"\StringFileInfo\lang-codepage\string-name"
Extract one of the version information strings in the resource. lang-codepage is an 8-digit hexadecimal value that identifies the code page and language used to encode the string. string-name is one of the following values that identify the various strings available:
"Comments"
"CompanyName"
"FileDescription"
"FileVersion"
"InternalName"
"LegalCopyright"
"LegalTrademarks"
"OriginalFilename"
"PrivateBuild"
"ProductName"
"ProductVersion"
"SpecialBuild"
lplpBuffer
Receives a pointer to the data extracted from the version information resource. The memory referenced by this pointer is automatically freed when the memory used by pBlock is freed. In other words, don't worry about freeing this memory after you use it.
puLen
Receives the size in bytes of the data referenced by the lplpBuffer pointer.

Note 1

The code page and language data comes as a series of four bytes. Before using the data, however, it needs to be modified slightly. You must swap the first two bytes with each other, and then swap the last two with each other. Then, you need to convert the four bytes into an 8-digit hexadecimal string, with the first byte (after the swap) at the beginning and the last byte at the end. For example, if "00" represents the first byte, "11" the second, etc., the string will look like "00112233". You are now ready to use this string as the lang-codepage component of a version information string identifier. Go back up.

Example

Display information about the file whose full path and filename is entered into textbox Text1. Display the version number, copyright information, and file description when button Command1 is pressed. To use this example, you obviously have to enter the filename of a 32-bit executable/DLL/etc. into Text1. Obviously, this example requires that you create a text box called Text1 and a command button called Command1.

' This code is licensed according to the terms and conditions listed here. ' Declarations and such needed for the example: ' (Copy them to the (declarations) section of a module.) Public Declare Function GetFileVersionInfo Lib "version.dll" Alias "GetFileVersionInfoA" _ (ByVal lptstrFilename As String, ByVal dwHandle As Long, ByVal dwLen As Long, _ lpData As Any) As Long Public Declare Function GetFileVersionInfoSize Lib "version.dll" Alias _ "GetFileVersionInfoSizeA" (ByVal lptstrFilename As String, lpdwHandle As Long) As Long Public Declare Function VerQueryValue Lib "version.dll" Alias "VerQueryValueA" (pBlock _ As Any, ByVal lpSubBlock As String, lplpBuffer As Long, puLen As Long) As Long Public Declare Function lstrcpy Lib "kernel32.dll" Alias "lstrcpyA" (ByVal lpString1 _ As Any, ByVal lpString2 As Any) As Long Public Declare Sub CopyMemory Lib "kernel32.dll" Alias "RtlMoveMemory" (Destination As Any, _ Source As Any, ByVal Length As Long) Public Type VS_FIXEDFILEINFO dwSignature As Long dwStrucVersion As Long dwFileVersionMS As Long dwFileVersionLS As Long dwProductVersionMS As Long dwProductVersionLS As Long dwFileFlagsMask As Long dwFileFlags As Long dwFileOS As Long dwFileType As Long dwFileSubtype As Long dwFileDateMS As Long dwFileDateLS As Long End Type Public Const VFT_APP = &H1 Public Const VFT_DLL = &H2 Public Const VFT_DRV = &H3 Public Const VFT_VXD = &H5 ' *** Place the following function definitions inside a module. *** ' HIWORD and LOWORD are API macros defined below. Public Function HIWORD (ByVal dwValue As Long) As Long Dim hexstr As String hexstr = Right("00000000" & Hex(dwValue), 8) HIWORD = CLng("&H" & Left(hexstr, 4)) End Function Public Function LOWORD (ByVal dwValue As Long) As Long Dim hexstr As String hexstr = Right("00000000" & Hex(dwValue), 8) LOWORD = CLng("&H" & Right(hexstr, 4)) End Function ' This nifty subroutine swaps two byte values without needing a buffer variable. ' This technique, which uses Xor, works as long as the two values to be swapped are ' numeric and of the same data type (here, both Byte). Public Sub SwapByte (byte1 As Byte, byte2 As Byte) byte1 = byte1 Xor byte2 byte2 = byte1 Xor byte2 byte1 = byte1 Xor byte2 End Sub ' This function creates a hexadecimal string to represent a number, but it ' outputs a string of a fixed number of digits.  Extra zeros are added to make ' the string the proper length.  The "&H" prefix is not put into the string. Public Function FixedHex (ByVal hexval As Long, ByVal nDigits As Long) As String FixedHex = Right("00000000" & Hex(hexval), nDigits) End Function ' *** Place the following code inside the form that has Command1 and Text1. *** Private Sub Command1_Click() Dim vffi As VS_FIXEDFILEINFO  ' version info structure Dim buffer() As Byte          ' buffer for version info resource Dim pData As Long             ' pointer to version info data Dim nDataLen As Long          ' length of info pointed at by pData Dim cpl(0 To 3) As Byte       ' buffer for code page & language Dim cplstr As String          ' 8-digit hex string of cpl Dim dispstr As String         ' string used to display version information Dim retval As Long            ' generic return value ' First, get the size of the version info resource.  If this function fails, then Text1 ' identifies a file that isn't a 32-bit executable/DLL/etc. nDataLen = GetFileVersionInfoSize(Text1.Text, pData) If nDataLen = 0 Then Debug.Print "Not a 32-bit executable!" Exit Sub End If ' Make the buffer large enough to hold the version info resource. ReDim buffer(0 To nDataLen - 1) As Byte ' Get the version information resource. retval = GetFileVersionInfo(Text1.Text, 0, nDataLen, buffer(0)) ' Get a pointer to a structure that holds a bunch of data. retval = VerQueryValue(buffer(0), "\", pData, nDataLen) ' Copy that structure into the one we can access. CopyMemory vffi, ByVal pData, nDataLen ' Display the full version number of the file. dispstr = Trim(Str(HIWORD(vffi.dwFileVersionMS))) & "." & _ Trim(Str(LOWORD(vffi.dwFileVersionMS))) & "." & _ Trim(Str(HIWORD(vffi.dwFileVersionLS))) & "." & _ Trim(Str(LOWORD(vffi.dwFileVersionLS))) Debug.Print "Version Number: "; dispstr ' Display the type of file it is (i.e., executable, DLL, etc.). Select Case vffi.dwFileType Case VFT_APP dispstr = "Application" Case VFT_DLL dispstr = "Dynamic Link Library (DLL)" Case VFT_DRV dispstr = "Device Driver" Case VFT_VXD dispstr = "Virtual Device Driver" Case Else dispstr = "Unknown" End Select Debug.Print "File Type: "; dispstr ' Before reading any strings out of the resource, we must first determine the code page ' and language.  The code to get this information follows. retval = VerQueryValue(buffer(0), "\VarFileInfo\Translation", pData, nDataLen) ' Copy that informtion into the byte array. CopyMemory cpl(0), ByVal pData, 4 ' It is necessary to swap the first two bytes, as well as the last two bytes. SwapByte cpl(0), cpl(1) SwapByte cpl(2), cpl(3) ' Convert those four bytes into a 8-digit hexadecimal string. cplstr = FixedHex(cpl(0), 2) & FixedHex(cpl(1), 2) & FixedHex(cpl(2), 2) & _ FixedHex(cpl(3), 2) ' cplstr now represents the code page and language to read strings as. ' Read the copyright information from the version info resource. retval = VerQueryValue(buffer(0), "\StringFileInfo\" & cplstr & "\LegalCopyright", _ pData, nDataLen) ' Copy that data into a string for display. dispstr = Space(nDataLen) retval = lstrcpy(dispstr, pData) ' Display the result. Debug.Print "Copyright Info: "; dispstr ' Similarly, read a description of the file and display it. retval = VerQueryValue(buffer(0), "\StringFileInfo\" & cplstr & "\FileDescription", _ pData, nDataLen) dispstr = Space(nDataLen) retval = lstrcpy(dispstr, pData) Debug.Print "File Description: "; dispstr End Sub

See Also

GetFileVersionInfo, GetFileVersionInfoSize

Category

Files

Back to the Function list.
Back to the Reference section.


Last Modified: July 30, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/v/verqueryvalue.html



Windows API Guide
Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems
ISBN: B001V0KQIY
EAN: N/A
Year: 1998
Pages: 610

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net