Kernel32Util (JNA API)

com.sun.jna.platform.win32

## Class Kernel32Util

- java.lang.Object
- - com.sun.jna.platform.win32.Kernel32Util

- All Implemented Interfaces:
    WinDef

      public abstract class Kernel32Util
      extends java.lang.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`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `VOLUME_GUID_PATH_PREFIX`
    `static java.lang.String` | `VOLUME_GUID_PATH_SUFFIX`

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

      `MAX_PATH`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `Kernel32Util()`

  - ### Method Summary

    All Methods Static Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static void` | `closeHandle(WinNT.HANDLE h)` Invokes `Kernel32.CloseHandle(WinNT.HANDLE)` and checks the success code.
    `static void` | `closeHandleRef(WinNT.HANDLEByReference ref)` Closes the handle in the reference
    `static void` | `closeHandleRefs(WinNT.HANDLEByReference... refs)` Closes all referenced handles.
    `static void` | `closeHandles(WinNT.HANDLE... handles)` Invokes `closeHandle(WinNT.HANDLE)` on each handle.
    `static void` | `deleteFile(java.lang.String filename)`
    `static java.lang.String` | `extractVolumeGUID(java.lang.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 java.lang.String` | `formatMessage(int code)` Format a message from the value obtained from `Kernel32.GetLastError()` or `Native.getLastError()`.
    `static java.lang.String` | `formatMessage(WinNT.HRESULT code)` Format a message from an HRESULT.
    `static java.lang.String` | `formatMessageFromHR(WinNT.HRESULT code)` Deprecated. use `formatMessage(WinNT.HRESULT)` instead.
    `static java.lang.String` | `formatMessageFromLastErrorCode(int code)` Format a system message from an error code.
    `static void` | `freeGlobalMemory(Pointer ptr)` Invokes `Kernel32.GlobalFree(Pointer)` and checks if it succeeded.
    `static void` | `freeLocalMemory(Pointer ptr)` Invokes `Kernel32.LocalFree(Pointer)` and checks if it succeeded.
    `static java.lang.String` | `getComputerName()` Get current computer NetBIOS name.
    `static int` | `getDriveType(java.lang.String rootName)`
    `static java.lang.String` | `getEnvironmentVariable(java.lang.String name)` Get the value of an environment variable.
    `static java.util.Map<java.lang.String,java.lang.String>` | `getEnvironmentVariables()` Uses the `Kernel32.GetEnvironmentStrings()` to retrieve and parse the current process environment
    `static java.util.Map<java.lang.String,java.lang.String>` | `getEnvironmentVariables(Pointer lpszEnvironmentBlock, long offset)`
    `static int` | `getFileAttributes(java.lang.String fileName)` Retrieves file system attributes for a specified file or directory.
    `static int` | `getFileType(java.lang.String fileName)` Retrieves the result of GetFileType, provided the file exists.
    `static java.lang.String` | `getLastErrorMessage()`
    `static java.util.List<java.lang.String>` | `getLogicalDriveStrings()` Returns valid drives in the system.
    `static WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION[]` | `getLogicalProcessorInformation()` Convenience method to get the processor information.
    `static java.util.List<Tlhelp32.MODULEENTRY32W>` | `getModules(int processID)` Returns all the executable modules for a given process ID.
    `static int` | `getPrivateProfileInt(java.lang.String appName, java.lang.String keyName, int defaultValue, java.lang.String fileName)` Retrieves an integer associated with a key in the specified section of an initialization file.
    `static java.lang.String[]` | `getPrivateProfileSection(java.lang.String appName, java.lang.String fileName)` Retrieves all the keys and values for the specified section of an initialization file.
    `static java.lang.String[]` | `getPrivateProfileSectionNames(java.lang.String fileName)` Retrieves the names of all sections in an initialization file.
    `static java.lang.String` | `getPrivateProfileString(java.lang.String lpAppName, java.lang.String lpKeyName, java.lang.String lpDefault, java.lang.String lpFileName)` Retrieves a string from the specified section in an initialization file.
    `static byte[]` | `getResource(java.lang.String path, java.lang.String type, java.lang.String name)` Gets the specified resource out of the specified executable file
    `static java.util.Map<java.lang.String,java.util.List<java.lang.String>>` | `getResourceNames(java.lang.String path)` Gets a list of all resources from the specified executable file
    `static java.lang.String` | `getTempPath()` Return the path designated for temporary files.
    `static java.util.List<java.lang.String>` | `getVolumePathNamesForVolumeName(java.lang.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" `char`s.
    `static java.util.List<java.lang.String>` | `queryDosDevice(java.lang.String lpszDeviceName, int maxTargetSize)` Invokes the `Kernel32.QueryDosDevice(String, char[], int)` method and parses the result
    `static java.lang.String` | `QueryFullProcessImageName(WinNT.HANDLE hProcess, int dwFlags)` This function retrieves the full path of the executable file of a given process.
    `static java.lang.String` | `readEnvironmentStringBlockEntry(Pointer lpszEnvironmentBlock, long offset, boolean asWideChars)`
    `static void` | `writePrivateProfileSection(java.lang.String appName, java.lang.String[] strings, java.lang.String fileName)`
    `static void` | `writePrivateProfileString(java.lang.String appName, java.lang.String keyName, java.lang.String string, java.lang.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 java.lang.String VOLUME_GUID_PATH_PREFIX

      See Also:
        Constant Field Values

    - #### VOLUME_GUID_PATH_SUFFIX

          public static final java.lang.String VOLUME_GUID_PATH_SUFFIX

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### Kernel32Util

          public Kernel32Util()

  - ### Method Detail

    - #### getComputerName

          public static java.lang.String getComputerName()

      Get current computer NetBIOS name.
      Returns:
        Netbios name.

    - #### freeLocalMemory

          public static void freeLocalMemory(Pointer ptr)

      Invokes `Kernel32.LocalFree(Pointer)` and checks if it succeeded.
      Parameters:
        `ptr` - The `Pointer` to the memory to be released - ignored if NULL
      Throws:
        `Win32Exception` - if non-`ERROR_SUCCESS` code reported

    - #### freeGlobalMemory

          public static void freeGlobalMemory(Pointer ptr)

      Invokes `Kernel32.GlobalFree(Pointer)` and checks if it succeeded.
      Parameters:
        `ptr` - The `Pointer` 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 if `null`
      See Also:
        `closeHandle(WinNT.HANDLE)`

    - #### closeHandles

          public static void closeHandles(WinNT.HANDLE... handles)

      Invokes `closeHandle(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)

      Invokes `Kernel32.CloseHandle(WinNT.HANDLE)` and checks the success code. If not successful, then throws a `Win32Exception` with the `GetLastError` value
      Parameters:
        `h` - The handle to be closed - ignored if `null`

    - #### formatMessage

          public static java.lang.String formatMessage(int code)

      Format a message from the value obtained from `Kernel32.GetLastError()` or `Native.getLastError()`.
      Parameters:
        `code` - The error code
      Returns:
        Formatted message.

    - #### formatMessage

          public static java.lang.String formatMessage(WinNT.HRESULT code)

      Format a message from an HRESULT.
      Parameters:
        `code` - HRESULT
      Returns:
        Formatted message.

    - #### formatMessageFromHR

          @Deprecated
          public static java.lang.String formatMessageFromHR(WinNT.HRESULT code)

      Deprecated. use `formatMessage(WinNT.HRESULT)` instead.
      Parameters:
        `code` - error code
      Returns:
        formatted message

    - #### formatMessageFromLastErrorCode

          public static java.lang.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 java.lang.String getLastErrorMessage()

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

    - #### getTempPath

          public static java.lang.String getTempPath()

      Return the path designated for temporary files.
      Returns:
        Path.

    - #### deleteFile

          public static void deleteFile(java.lang.String filename)

    - #### getLogicalDriveStrings

          public static java.util.List<java.lang.String> getLogicalDriveStrings()

      Returns valid drives in the system.
      Returns:
        A `List` of valid drives.

    - #### getFileAttributes

          public static int getFileAttributes(java.lang.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(java.lang.String fileName)
                                 throws java.io.FileNotFoundException

      Retrieves the result of GetFileType, provided the file exists.
      Parameters:
        `fileName` - file name
      Returns:
        file type
      Throws:
        `java.io.FileNotFoundException` - if file not found

    - #### getDriveType

          public static int getDriveType(java.lang.String rootName)

      Parameters:
        `rootName` - name of root drive
      Returns:
        One of the WinBase.DRIVE_* constants.

    - #### getEnvironmentVariable

          public static java.lang.String getEnvironmentVariable(java.lang.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 java.util.Map<java.lang.String,java.lang.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 java.util.Map<java.lang.String,java.lang.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 java.lang.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" `char`s
      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" `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`
      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" `char`s

    - #### getPrivateProfileInt

          public static final int getPrivateProfileInt(java.lang.String appName,
                                                       java.lang.String keyName,
                                                       int defaultValue,
                                                       java.lang.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 java.lang.String getPrivateProfileString(java.lang.String lpAppName,
                                                                       java.lang.String lpKeyName,
                                                                       java.lang.String lpDefault,
                                                                       java.lang.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(java.lang.String appName,
                                                             java.lang.String keyName,
                                                             java.lang.String string,
                                                             java.lang.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 java.lang.String[] getPrivateProfileSection(java.lang.String appName,
                                                                          java.lang.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 java.lang.String[] getPrivateProfileSectionNames(java.lang.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(java.lang.String appName,
                                                              java.lang.String[] strings,
                                                              java.lang.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 java.util.List<java.lang.String> queryDosDevice(java.lang.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 java.util.List<java.lang.String> getVolumePathNamesForVolumeName(java.lang.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 java.lang.String extractVolumeGUID(java.lang.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:
        `java.lang.IllegalArgumentException` - if bad format encountered
      See Also:
        Naming a Volume

    - #### QueryFullProcessImageName

          public static final java.lang.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 process
        `dwFlags` - 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(java.lang.String path,
                                           java.lang.String type,
                                           java.lang.String name)

      Gets the specified resource out of the specified executable file
      Parameters:
        `path` - The path to the executable file
        `type` - 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:
        `java.lang.IllegalStateException` - if the call to LockResource fails

    - #### getResourceNames

          public static java.util.Map<java.lang.String,java.util.List<java.lang.String>> getResourceNames(java.lang.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 java.util.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.

Copyright © 2007-2016 Timothy Wall. All Rights Reserved.