Class Kernel32Util
- java.lang.Object
-
- com.sun.jna.platform.win32.Kernel32Util
-
-
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.HKL, 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
-
-
Field Summary
Fields Modifier and Type Field Description static String
VOLUME_GUID_PATH_PREFIX
static String
VOLUME_GUID_PATH_SUFFIX
-
Constructor Summary
Constructors Constructor Description Kernel32Util()
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
closeHandle(WinNT.HANDLE h)
InvokesKernel32.CloseHandle(WinNT.HANDLE)
and checks the success code.static void
closeHandleRef(WinNT.HANDLEByReference ref)
Closes the handle in the referencestatic void
closeHandleRefs(WinNT.HANDLEByReference... refs)
Closes all referenced handles.static void
closeHandles(WinNT.HANDLE... handles)
InvokescloseHandle(WinNT.HANDLE)
on each handle.static void
deleteFile(String filename)
static String
expandEnvironmentStrings(String input)
Expands environment-variable strings and replaces them with the values defined for the current user.static String
extractVolumeGUID(String volumeGUIDPath)
Parses and returns the pure GUID value of a volume name obtained fromKernel32.FindFirstVolume(char[], int)
orKernel32.FindNextVolume(com.sun.jna.platform.win32.WinNT.HANDLE, char[], int)
callsstatic long
findEnvironmentStringBlockEntryEnd(Pointer lpszEnvironmentBlock, long offset, boolean asWideChars)
static String
formatMessage(int code)
Format a message from the value obtained fromKernel32.GetLastError()
orNative.getLastError()
.static String
formatMessage(WinNT.HRESULT code)
Format a message from an HRESULT.static String
formatMessageFromLastErrorCode(int code)
Format a system message from an error code.static void
freeGlobalMemory(Pointer ptr)
InvokesKernel32.GlobalFree(Pointer)
and checks if it succeeded.static void
freeLocalMemory(Pointer ptr)
InvokesKernel32.LocalFree(Pointer)
and checks if it succeeded.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 theKernel32.GetEnvironmentStrings()
to retrieve and parse the current process environmentstatic 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 WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX[]
getLogicalProcessorInformationEx(int relationshipType)
Convenience method to get the processor information.static List<Tlhelp32.MODULEENTRY32W>
getModules(int processID)
Returns all the executable modules for a given process ID.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 byte[]
getResource(String path, String type, String name)
Gets the specified resource out of the specified executable filestatic Map<String,List<String>>
getResourceNames(String path)
Gets a list of all resources from the specified executable filestatic String
getTempPath()
Return the path designated for temporary files.static List<String>
getVolumePathNamesForVolumeName(String lpszVolumeName)
Invokes and parses the result ofKernel32.GetVolumePathNamesForVolumeName(String, char[], int, IntByReference)
static boolean
isWideCharEnvironmentStringBlock(Pointer lpszEnvironmentBlock, long offset)
Attempts to determine whether the data block useswchar_t
instead of "plain old"char
s.static List<String>
queryDosDevice(String lpszDeviceName, int maxTargetSize)
Invokes theKernel32.QueryDosDevice(String, char[], int)
method and parses the resultstatic String
QueryFullProcessImageName(int pid, int dwFlags)
This function retrieves the full path of the executable file of a given process identifier.static String
QueryFullProcessImageName(WinNT.HANDLE hProcess, int dwFlags)
This function retrieves the full path of the executable file of a given process.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)
-
-
-
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
-
-
Method Detail
-
getComputerName
public static String getComputerName()
Get current computer NetBIOS name.- Returns:
- Netbios name.
-
freeLocalMemory
public static void freeLocalMemory(Pointer ptr)
InvokesKernel32.LocalFree(Pointer)
and checks if it succeeded.- Parameters:
ptr
- ThePointer
to the memory to be released - ignored if NULL- Throws:
Win32Exception
- if non-ERROR_SUCCESS
code reported
-
freeGlobalMemory
public static void freeGlobalMemory(Pointer ptr)
InvokesKernel32.GlobalFree(Pointer)
and checks if it succeeded.- Parameters:
ptr
- ThePointer
to the memory to be released - ignored if NULL- Throws:
Win32Exception
- if non-ERROR_SUCCESS
code reported
-
closeHandleRefs
public static void closeHandleRefs(WinNT.HANDLEByReference... refs)
Closes all referenced handles. If an exception is thrown for a specific handle, then it is accumulated until all handles have been closed. If more than one exception occurs, then it is added as a suppressed exception to the first one. Once closed all handles, the accumulated exception (if any) is thrown- Parameters:
refs
- The references to close- See Also:
closeHandleRef(WinNT.HANDLEByReference)
-
closeHandleRef
public static void closeHandleRef(WinNT.HANDLEByReference ref)
Closes the handle in the reference- Parameters:
ref
- The handle reference - ignored ifnull
- See Also:
closeHandle(WinNT.HANDLE)
-
closeHandles
public static void closeHandles(WinNT.HANDLE... handles)
InvokescloseHandle(WinNT.HANDLE)
on each handle. If an exception is thrown for a specific handle, then it is accumulated until all handles have been closed. If more than one exception occurs, then it is added as a suppressed exception to the first one. Once closed all handles, the accumulated exception (if any) is thrown- Parameters:
handles
- The handles to be closed- See Also:
Throwable.getSuppressed()
-
closeHandle
public static void closeHandle(WinNT.HANDLE h)
InvokesKernel32.CloseHandle(WinNT.HANDLE)
and checks the success code. If not successful, then throws aWin32Exception
with theGetLastError
value- Parameters:
h
- The handle to be closed - ignored ifnull
-
formatMessage
public static String formatMessage(int code)
Format a message from the value obtained fromKernel32.GetLastError()
orNative.getLastError()
.- Parameters:
code
- The error code- Returns:
- Formatted message.
-
formatMessage
public static String formatMessage(WinNT.HRESULT code)
Format a message from an HRESULT.- Parameters:
code
- HRESULT- 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 theKernel32.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 functionoffset
- Offset within the block to parse the data- Returns:
- A
Map
of the parsedname=value
pairs. Note: if the environment block isnull
thennull
is returned instead of an empty map since we want to distinguish between the case that the data block isnull
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 functionoffset
- Offset within the block to look for the entryasWideChars
- Iftrue
then the block containswchar_t
instead of "plain old"char
s- Returns:
- A
String
containing thename=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 functionoffset
- Offset within the block to look for the entryasWideChars
- Iftrue
then the block containswchar_t
instead of "plain old"char
s- 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"char
s. 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"
char
s 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
ByteOrder
even though onlyByteOrder.LITTLE_ENDIAN
is the likely one- Parameters:
lpszEnvironmentBlock
- The environment block as received from the GetEnvironmentStrings functionoffset
- offset- Returns:
true
if the block containswchar_t
instead of "plain old"char
s
-
If the charset indicator is non-zero then it is assumed to be
a "plain old"
-
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; theKernel32.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 isnull
, theKernel32.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 isnull
, all key names in the section specified by thelpAppName
parameter are returned.lpDefault
- A default string. If thelpKeyName
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 isnull
, the default is an empty string,""
.Avoid specifying a default string with trailing blank characters. The function inserts a
null
character in thelpReturnedString
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
norlpKeyName
isnull
and the destination buffer is too small to hold the requested string, the string is truncated.If either
lpAppName
orlpKeyName
isnull
and the destination buffer is too small to hold all the strings, the last string is truncated and followed by twonull
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, callKernel32.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.
-
getLogicalProcessorInformationEx
public static final WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX[] getLogicalProcessorInformationEx(int relationshipType)
Convenience method to get the processor information. Takes care of auto-growing the array and populating variable-length arrays in structures.- Parameters:
relationshipType
- The type of relationship to retrieve. This parameter can be one of the following values:WinNT.LOGICAL_PROCESSOR_RELATIONSHIP.RelationCache
,WinNT.LOGICAL_PROCESSOR_RELATIONSHIP.RelationGroup
,WinNT.LOGICAL_PROCESSOR_RELATIONSHIP.RelationNumaNode
,WinNT.LOGICAL_PROCESSOR_RELATIONSHIP.RelationProcessorCore
,WinNT.LOGICAL_PROCESSOR_RELATIONSHIP.RelationProcessorPackage
, orWinNT.LOGICAL_PROCESSOR_RELATIONSHIP.RelationAll
- 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 isNULL
, 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 formkey=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 theKernel32.QueryDosDevice(String, char[], int)
method and parses the result- Parameters:
lpszDeviceName
- The device namemaxTargetSize
- 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 ofKernel32.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 fromKernel32.FindFirstVolume(char[], int)
orKernel32.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
-
QueryFullProcessImageName
public static final String QueryFullProcessImageName(int pid, int dwFlags)
This function retrieves the full path of the executable file of a given process identifier.- Parameters:
pid
- Identifier for the running processdwFlags
- 0 - The name should use the Win32 path format. 1(WinNT.PROCESS_NAME_NATIVE) - The name should use the native system path format.- Returns:
- the full path of the process's executable file of null if failed. To get extended error information, call GetLastError.
-
QueryFullProcessImageName
public static final String QueryFullProcessImageName(WinNT.HANDLE hProcess, int dwFlags)
This function retrieves the full path of the executable file of a given process.- Parameters:
hProcess
- Handle for the running processdwFlags
- 0 - The name should use the Win32 path format. 1(WinNT.PROCESS_NAME_NATIVE) - The name should use the native system path format.- Returns:
- the full path of the process's executable file of null if failed. To get extended error information, call GetLastError.
-
getResource
public static byte[] getResource(String path, String type, String name)
Gets the specified resource out of the specified executable file- Parameters:
path
- The path to the executable filetype
- The type of the resource (either a type name or type ID is allowed)name
- The name or ID of the resource- Returns:
- The resource bytes, or null if no such resource exists.
- Throws:
IllegalStateException
- if the call to LockResource fails
-
getResourceNames
public static Map<String,List<String>> getResourceNames(String path)
Gets a list of all resources from the specified executable file- Parameters:
path
- The path to the executable file- Returns:
- A map of resource type name/ID => resources.
A map key + a single list item + the path to the executable can be handed off to getResource() to actually get the resource.
-
getModules
public static List<Tlhelp32.MODULEENTRY32W> getModules(int processID)
Returns all the executable modules for a given process ID.- Parameters:
processID
- The process ID to get executable modules for- Returns:
- All the modules in the process.
-
expandEnvironmentStrings
public static String expandEnvironmentStrings(String input)
Expands environment-variable strings and replaces them with the values defined for the current user.- Parameters:
input
- A string that contains one or more environment-variable strings in the form: %variableName%. For each such reference, the %variableName% portion is replaced with the current value of that environment variable.Case is ignored when looking up the environment-variable name. If the name is not found, the %variableName% portion is left unexpanded.
Note that this function does not support all the features that Cmd.exe supports. For example, it does not support %variableName:str1=str2% or %variableName:~offset,length%.
- Returns:
- the replaced string
- Throws:
Win32Exception
- if an error occurs
-
-