com.sun.jna.platform.win32

Class Kernel32Util

java.lang.Object

com.sun.jna.platform.win32.Kernel32Util

All Implemented Interfaces:

AltCallingConvention, Library, WinDef, StdCall, StdCallLibrary

public abstract class Kernel32Util
extends Object
implements WinDef

Kernel32 utility API.

Author:

dblock[at]dblock.org, markus[at]headcrashing[dot]eu, Andreas "PAX" Lück, onkelpax-git[at]yahoo.de

Nested Class Summary

Nested classes/interfaces inherited from interface com.sun.jna.platform.win32.WinDef

WinDef.ATOM, WinDef.BOOL, WinDef.BOOLByReference, WinDef.BYTE, WinDef.CHAR, WinDef.CHARByReference, WinDef.DWORD, WinDef.DWORDByReference, WinDef.DWORDLONG, WinDef.HBITMAP, WinDef.HBRUSH, WinDef.HCURSOR, WinDef.HDC, WinDef.HFONT, WinDef.HGLRC, WinDef.HGLRCByReference, WinDef.HICON, WinDef.HINSTANCE, WinDef.HMENU, WinDef.HMODULE, WinDef.HPALETTE, WinDef.HPEN, WinDef.HRGN, WinDef.HRSRC, WinDef.HWND, WinDef.INT_PTR, WinDef.LCID, WinDef.LONG, WinDef.LONGByReference, WinDef.LONGLONG, WinDef.LONGLONGByReference, WinDef.LPARAM, WinDef.LPVOID, WinDef.LRESULT, WinDef.POINT, WinDef.PVOID, WinDef.RECT, WinDef.SCODE, WinDef.SCODEByReference, WinDef.SHORT, WinDef.UCHAR, WinDef.UINT, WinDef.UINT_PTR, WinDef.UINTByReference, WinDef.ULONG, WinDef.ULONGByReference, WinDef.ULONGLONG, WinDef.ULONGLONGByReference, WinDef.USHORT, WinDef.USHORTByReference, WinDef.WORD, WinDef.WORDByReference, WinDef.WPARAM

Nested classes/interfaces inherited from interface com.sun.jna.win32.StdCallLibrary

StdCallLibrary.StdCallCallback

Nested classes/interfaces inherited from interface com.sun.jna.Library

Library.Handler

Field Summary

Fields

Modifier and Type	Field and Description
static String	VOLUME_GUID_PATH_PREFIX
static String	VOLUME_GUID_PATH_SUFFIX

Fields inherited from interface com.sun.jna.platform.win32.WinDef

MAX_PATH

Fields inherited from interface com.sun.jna.win32.StdCallLibrary

FUNCTION_MAPPER, STDCALL_CONVENTION

Fields inherited from interface com.sun.jna.Library

OPTION_ALLOW_OBJECTS, OPTION_CALLING_CONVENTION, OPTION_CLASSLOADER, OPTION_FUNCTION_MAPPER, OPTION_INVOCATION_MAPPER, OPTION_OPEN_FLAGS, OPTION_STRING_ENCODING, OPTION_STRUCTURE_ALIGNMENT, OPTION_TYPE_MAPPER

Constructor Summary

Constructors

Constructor and Description
Kernel32Util()

Method Summary

Modifier and Type	Method and Description
static void	deleteFile(String filename)
static String	extractVolumeGUID(String volumeGUIDPath) Parses and returns the pure GUID value of a volume name obtained from Kernel32.FindFirstVolume(char[], int) or Kernel32.FindNextVolume(com.sun.jna.platform.win32.WinNT.HANDLE, char[], int) calls
static long	findEnvironmentStringBlockEntryEnd(Pointer lpszEnvironmentBlock, long offset, boolean asWideChars)
static String	formatMessage(int code) Format a message from the value obtained from Kernel32.GetLastError() or Native.getLastError().
static String	formatMessage(WinNT.HRESULT code) Format a message from an HRESULT.
static String	formatMessageFromHR(WinNT.HRESULT code) Deprecated. use formatMessage(WinNT.HRESULT) instead.
static String	formatMessageFromLastErrorCode(int code) Format a system message from an error code.
static String	getComputerName() Get current computer NetBIOS name.
static int	getDriveType(String rootName)
static String	getEnvironmentVariable(String name) Get the value of an environment variable.
static Map<String,String>	getEnvironmentVariables() Uses the Kernel32.GetEnvironmentStrings() to retrieve and parse the current process environment
static Map<String,String>	getEnvironmentVariables(Pointer lpszEnvironmentBlock, long offset)
static int	getFileAttributes(String fileName) Retrieves file system attributes for a specified file or directory.
static int	getFileType(String fileName) Retrieves the result of GetFileType, provided the file exists.
static String	getLastErrorMessage()
static List<String>	getLogicalDriveStrings() Returns valid drives in the system.
static WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION[]	getLogicalProcessorInformation() Convenience method to get the processor information.
static int	getPrivateProfileInt(String appName, String keyName, int defaultValue, String fileName) Retrieves an integer associated with a key in the specified section of an initialization file.
static String[]	getPrivateProfileSection(String appName, String fileName) Retrieves all the keys and values for the specified section of an initialization file.
static String[]	getPrivateProfileSectionNames(String fileName) Retrieves the names of all sections in an initialization file.
static String	getPrivateProfileString(String lpAppName, String lpKeyName, String lpDefault, String lpFileName) Retrieves a string from the specified section in an initialization file.
static String	getTempPath() Return the path designated for temporary files.
static List<String>	getVolumePathNamesForVolumeName(String lpszVolumeName) Invokes and parses the result of Kernel32.GetVolumePathNamesForVolumeName(String, char[], int, IntByReference)
static boolean	isWideCharEnvironmentStringBlock(Pointer lpszEnvironmentBlock, long offset) Attempts to determine whether the data block uses wchar_t instead of "plain old" chars.
static List<String>	queryDosDevice(String lpszDeviceName, int maxTargetSize) Invokes the Kernel32.QueryDosDevice(String, char[], int) method and parses the result
static String	readEnvironmentStringBlockEntry(Pointer lpszEnvironmentBlock, long offset, boolean asWideChars)
static void	writePrivateProfileSection(String appName, String[] strings, String fileName)
static void	writePrivateProfileString(String appName, String keyName, String string, String fileName)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

VOLUME_GUID_PATH_PREFIX

public static final String VOLUME_GUID_PATH_PREFIX

See Also:

Constant Field Values

VOLUME_GUID_PATH_SUFFIX

public static final String VOLUME_GUID_PATH_SUFFIX

See Also:

Constant Field Values

Constructor Detail

Kernel32Util

public Kernel32Util()

Method Detail

getComputerName

public static String getComputerName()

Get current computer NetBIOS name.

Returns:

Netbios name.

formatMessage

public static String formatMessage(int code)

Format a message from the value obtained from Kernel32.GetLastError() or Native.getLastError().

Parameters:

code - int

Returns:

Formatted message.

formatMessage

public static String formatMessage(WinNT.HRESULT code)

Format a message from an HRESULT.

Parameters:

code - HRESULT

Returns:

Formatted message.

formatMessageFromHR

public static String formatMessageFromHR(WinNT.HRESULT code)

Deprecated. use formatMessage(WinNT.HRESULT) instead.

Parameters:

code - error code

Returns:

formatted message

formatMessageFromLastErrorCode

public static String formatMessageFromLastErrorCode(int code)

Format a system message from an error code.

Parameters:

code - Error code, typically a result of GetLastError.

Returns:

Formatted message.

getLastErrorMessage

public static String getLastErrorMessage()

Returns:

Obtains the human-readable error message text from the last error that occurred by invocating Kernel32.GetLastError().

getTempPath

public static String getTempPath()

Return the path designated for temporary files.

Returns:

Path.

deleteFile

public static void deleteFile(String filename)

getLogicalDriveStrings

public static List<String> getLogicalDriveStrings()

Returns valid drives in the system.

Returns:

A List of valid drives.

getFileAttributes

public static int getFileAttributes(String fileName)

Retrieves file system attributes for a specified file or directory.

Parameters:

fileName - The name of the file or directory.

Returns:

The attributes of the specified file or directory.

getFileType

public static int getFileType(String fileName)
                       throws FileNotFoundException

Retrieves the result of GetFileType, provided the file exists.

Parameters:

fileName - file name

Returns:

file type

Throws:

FileNotFoundException - if file not found

getDriveType

public static int getDriveType(String rootName)

Parameters:

rootName - name of root drive

Returns:

One of the WinBase.DRIVE_* constants.

getEnvironmentVariable

public static String getEnvironmentVariable(String name)

Get the value of an environment variable.

Parameters:

name - Name of the environment variable.

Returns:

Value of an environment variable.

getEnvironmentVariables

public static Map<String,String> getEnvironmentVariables()

Uses the Kernel32.GetEnvironmentStrings() to retrieve and parse the current process environment

Returns:

The current process environment as a Map.

Throws:

LastErrorException - if failed to get or free the environment data block

See Also:

getEnvironmentVariables(Pointer, long)

getEnvironmentVariables

public static Map<String,String> getEnvironmentVariables(Pointer lpszEnvironmentBlock,
                                                         long offset)

Parameters:

lpszEnvironmentBlock - The environment block as received from the GetEnvironmentStrings function

offset - Offset within the block to parse the data

Returns:

A Map of the parsed name=value pairs. Note: if the environment block is null then null is returned instead of an empty map since we want to distinguish between the case that the data block is null and when there are no environment variables (as unlikely as it may be)

readEnvironmentStringBlockEntry

public static String readEnvironmentStringBlockEntry(Pointer lpszEnvironmentBlock,
                                                     long offset,
                                                     boolean asWideChars)

Parameters:

lpszEnvironmentBlock - The environment block as received from the GetEnvironmentStrings function

offset - Offset within the block to look for the entry

asWideChars - If true then the block contains wchar_t instead of "plain old" chars

Returns:

A String containing the name=value pair or empty if reached end of block

See Also:

isWideCharEnvironmentStringBlock(com.sun.jna.Pointer, long), findEnvironmentStringBlockEntryEnd(com.sun.jna.Pointer, long, boolean)

findEnvironmentStringBlockEntryEnd

public static long findEnvironmentStringBlockEntryEnd(Pointer lpszEnvironmentBlock,
                                                      long offset,
                                                      boolean asWideChars)

Parameters:

lpszEnvironmentBlock - The environment block as received from the GetEnvironmentStrings function

offset - Offset within the block to look for the entry

asWideChars - If true then the block contains wchar_t instead of "plain old" chars

Returns:

The offset of the first '\0' in the data block starting at the specified offset - can be the start offset itself if empty string.

See Also:

isWideCharEnvironmentStringBlock(com.sun.jna.Pointer, long)

isWideCharEnvironmentStringBlock

public static boolean isWideCharEnvironmentStringBlock(Pointer lpszEnvironmentBlock,
                                                       long offset)

Attempts to determine whether the data block uses wchar_t instead of "plain old" chars. It does that by reading 2 bytes from the specified offset - the character value and its charset indicator - and examining them as follows:

• If the charset indicator is non-zero then it is assumed to be a "plain old" chars data block. Note: the assumption is that the environment variable name (at least) is ASCII.
• Otherwise (i.e., zero charset indicator), it is assumed to be a wchar_t

Note: the code takes into account the ByteOrder even though only ByteOrder.LITTLE_ENDIAN is the likely one

Parameters:

lpszEnvironmentBlock - The environment block as received from the GetEnvironmentStrings function

offset - offset

Returns:

true if the block contains wchar_t instead of "plain old" chars

getPrivateProfileInt

public static final int getPrivateProfileInt(String appName,
                                             String keyName,
                                             int defaultValue,
                                             String fileName)

Retrieves an integer associated with a key in the specified section of an initialization file.

Parameters:

appName - The name of the section in the initialization file.

keyName - The name of the key whose value is to be retrieved. This value is in the form of a string; the Kernel32.GetPrivateProfileInt(java.lang.String, java.lang.String, int, java.lang.String) function converts the string into an integer and returns the integer.

defaultValue - The default value to return if the key name cannot be found in the initialization file.

fileName - The name of the initialization file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.

Returns:

The retrieved integer, or the default if not found.

getPrivateProfileString

public static final String getPrivateProfileString(String lpAppName,
                                                   String lpKeyName,
                                                   String lpDefault,
                                                   String lpFileName)

Retrieves a string from the specified section in an initialization file.

Parameters:

lpAppName - The name of the section containing the key name. If this parameter is null, the Kernel32.GetPrivateProfileString(java.lang.String, java.lang.String, java.lang.String, char[], com.sun.jna.platform.win32.WinDef.DWORD, java.lang.String) function copies all section names in the file to the supplied buffer.

lpKeyName - The name of the key whose associated string is to be retrieved. If this parameter is null, all key names in the section specified by the lpAppName parameter are returned.

lpDefault - A default string. If the lpKeyName key cannot be found in the initialization file, Kernel32.GetPrivateProfileString(java.lang.String, java.lang.String, java.lang.String, char[], com.sun.jna.platform.win32.WinDef.DWORD, java.lang.String) returns the default. If this parameter is null, the default is an empty string, "".

Avoid specifying a default string with trailing blank characters. The function inserts a null character in the lpReturnedString buffer to strip any trailing blanks.

lpFileName - The name of the initialization file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.

Returns:

If neither lpAppName nor lpKeyName is null and the destination buffer is too small to hold the requested string, the string is truncated.

If either lpAppName or lpKeyName is null and the destination buffer is too small to hold all the strings, the last string is truncated and followed by two null characters.

In the event the initialization file specified by lpFileName is not found, or contains invalid values, this function will set errorno with a value of '0x2' (File Not Found). To retrieve extended error information, call Kernel32.GetLastError().

writePrivateProfileString

public static final void writePrivateProfileString(String appName,
                                                   String keyName,
                                                   String string,
                                                   String fileName)

getLogicalProcessorInformation

public static final WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION[] getLogicalProcessorInformation()

Convenience method to get the processor information. Takes care of auto-growing the array.

Returns:

the array of processor information.

getPrivateProfileSection

public static final String[] getPrivateProfileSection(String appName,
                                                      String fileName)

Retrieves all the keys and values for the specified section of an initialization file.

Each string has the following format: key=string.

This operation is atomic; no updates to the specified initialization file are allowed while this method is executed.

Parameters:

appName - The name of the section in the initialization file.

fileName - The name of the initialization file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.

Returns:

The key name and value pairs associated with the named section.

getPrivateProfileSectionNames

public static final String[] getPrivateProfileSectionNames(String fileName)

Retrieves the names of all sections in an initialization file.

This operation is atomic; no updates to the initialization file are allowed while this method is executed.

Parameters:

fileName - The name of the initialization file. If this parameter is NULL, the function searches the Win.ini file. If this parameter does not contain a full path to the file, the system searches for the file in the Windows directory.

Returns:

the section names associated with the named file.

writePrivateProfileSection

public static final void writePrivateProfileSection(String appName,
                                                    String[] strings,
                                                    String fileName)

Parameters:

appName - The name of the section in which data is written. This section name is typically the name of the calling application.

strings - The new key names and associated values that are to be written to the named section. Each entry must be of the form key=value.

fileName - The name of the initialization file. If this parameter does not contain a full path for the file, the function searches the Windows directory for the file. If the file does not exist and lpFileName does not contain a full path, the function creates the file in the Windows directory.

queryDosDevice

public static final List<String> queryDosDevice(String lpszDeviceName,
                                                int maxTargetSize)

Invokes the Kernel32.QueryDosDevice(String, char[], int) method and parses the result

Parameters:

lpszDeviceName - The device name

maxTargetSize - The work buffer size to use for the query

Returns:

The parsed result

getVolumePathNamesForVolumeName

public static final List<String> getVolumePathNamesForVolumeName(String lpszVolumeName)

Invokes and parses the result of Kernel32.GetVolumePathNamesForVolumeName(String, char[], int, IntByReference)

Parameters:

lpszVolumeName - The volume name

Returns:

The parsed result

Throws:

Win32Exception - If failed to retrieve the required information

extractVolumeGUID

public static final String extractVolumeGUID(String volumeGUIDPath)

Parses and returns the pure GUID value of a volume name obtained from Kernel32.FindFirstVolume(char[], int) or Kernel32.FindNextVolume(com.sun.jna.platform.win32.WinNT.HANDLE, char[], int) calls

Parameters:

volumeGUIDPath - The volume GUID path as returned by one of the above mentioned calls

Returns:

The pure GUID value after stripping the "\\?\" prefix and removing the trailing backslash.

Throws:

IllegalArgumentException - if bad format encountered

See Also:

Naming a Volume