Win32API::ProcessStatus - Perl extension for obtaining information about processes using the plain Win32 PSAPI

- NAME
- SYNOPSIS
- DESCRIPTION

- EXPORTS
- STRUCTURES
- FUNCTIONS

- AUTHOR
- COPYRIGHT
- SEE ALSO

# NAME

Win32API::ProcessStatus - Perl extension for obtaining information about processes using the plain Win32 PSAPI

# SYNOPSIS

      use Win32API::ProcessStatus ':All';

      # --- prints IDs of all processes
      my $IDs;
      EnumerateProceses($IDs);
      foreach my $ID (@$IDs) {
        print "$ID ";
      }

# DESCRIPTION

The ProcessStatus helper functions make it easier for you to obtain information about processes.

It covers enumerating the currently running processes and their modules. The results are return in a form as close as possible to the original Win32 API (simple types are returned as scalars of the same type, arrays as references to arrays and structures as references to hashes with keys of the same names as the members of the original structures have). There are only process and module handling functions of the ProcessStatus helper implemented in this module (in the meanwhile).

These functions are available in Psapi.dll, which is included in Windows 2000 or higher. To use these functions on Windows NT, you must obtain the redistributable version of this DLL. It is not included in Windows 95 or higher. See the module Win32API::ToolHelp for the similar functionality for Windows 95 or higher.

(Note that much of the following documentation refers to the behavior of the underlying Win32 ProcessStatus API calls which may vary in its current and future versions without any changes to this module. Therefore you should check the Win32 ProcessStatus API documentation in MSDN directly when needed.)

## EXPORTS

Nothing is exported by default. The following tags can be used to have sets of symbols exported:

:Func
  The basic function names: EnumProcesses EnumProcessModules GetModuleBaseName GetModuleFileNameEx GetModuleInformation.

:FuncA
  The ANSI function names: GetModuleBaseNameA GetModuleFileNameExA.

:FuncW
  The Unicode function names: GetModuleBaseNameW GetModuleFileNameExW.

## STRUCTURES

The structures that act as input and ouput parameters are handled as hashes with keys of the same names as the members in the original structures have. It allows those already familiar with the Win32 API to get off to a quick start and occasionally use the original MSDN documentation to the API.

MODULEINFO
  Contains the module load address, size, and entry point.
  lpBaseOfDll
    The load address of the module.

  SizeOfImage
    The size, in bytes, of the linear space that the module occupies.

  EntryPoint
    The entry point of the module.

  The load address of a module is the same as the `HMODULE` value. The information returned in the `SizeOfImage` and `EntryPoint` members comes from the module's Portable Executable (PE) header. The module entry point is the location called during process startup, thread startup, process shutdown, and thread shutdown. While this is not the address of the `DllMain` function, it should be close enough for most purposes.

## FUNCTIONS

ProcessStatus functions return either a boolean status of the function's result or a number of characters filled into the output buffer. To retrieve an extended information about the error if it occurs use the `GetLastProcessStatusError` function. If no error happens `GetLastProcessStatusError` still returns the last occured error code (successful calls do not modify the last stored error code). You can set or reset the internally stored error code explicitely by the function `SetLastProcessStatusError`.

To use something more convenient than numbers for comparisons of return values and error codes see the module `Win32API::Const`.

There are couple of functions that are implemented as ANSI versions on Windows 95 or higher and as both ANSI and Unicode versions on Windows 2000 or higher. ANSI versions are named XxxA and Unicode versions XxxW just like the Win32 ProcessStatus originals. If you omit the last A/W letter the ANSI version is used as strings are ANSI in Perl's internals. Results of Unicode functions are converted into ANSI before returned.

EnumProcesses($lpidProcess, $cb, $lpcbNeeded)
  Retrieves the process identifier for each process object in the system.
  lpidProcess [OUT]
    Reference to an array that receives the list of process identifiers.

  cb [IN]
    Specifies the size, in bytes, of the lpidProcess array. It defaults to `4096 (1024 * sizeof(DWORD))` if omitted.

  lpcbNeeded [OUT]
    Receives the number of bytes returned in the `lpidProcess` array. It can be omitted if not needed.

  [RETVAL]
    If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call `GetLastProcessStatusError`.

  It is a good idea to give `EnumProcesses` a large array of `DWORD` values, because it is hard to predict how many processes there will be at the time you call `EnumProcesses`. To determine how many processes were enumerated by the call to `EnumProcesses`, divide the resulting value in the `cbNeeded` parameter by `sizeof(DWORD)`. There is no indication given when the buffer is too small to store all process identifiers.

  To obtain process handles for the processes whose identifiers you have just obtained, call the `OpenProcess` function.

EnumProcessModules($hProcess, $lphModule, $cb, $lpcbNeeded)
  Retrieves a handle for each module in the specified process.
  hProcess [IN]
    Handle to the process.

  lphModule [OUT]
    Reference to the array that receives the list of module handles.

  cb [IN]
    Specifies the size, in bytes, of the `lphModule` array. It defaults to `4096 (1024 * sizeof(DWORD))` if omitted.

  lpcbNeeded [OUT]
    Receives the number of bytes required to store all module handles in the `lphModule` array. It can be omitted if not needed.

  [RETVAL]
    If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call `GetLastProcessStatusError`.

  It is a good idea to give `EnumProcessModules` a large array of `HMODULE` values, because it is hard to predict how many modules there will be in the process at the time you call `EnumProcessModules`. To determine if the `lphModule` array is too small to hold all module handles for the process, compare the value returned in `lpcbNeeded` with the value specified in `cb`. If `lpcbNeeded` is greater than `cb`, increase the size of the array and call `EnumProcessModules` again.

  To determine how many modules were enumerated by the call to `EnumProcessModules`, divide the resulting value in the `lpcbNeeded` parameter by `sizeof(HMODULE)`.

`GetLastProcessStatusError()`
  Retrieves the last-error code value of the ProcessStatus functions. The last-error code is stored if a function fails and remembered until another function calls when it is overwritten by the new error code. Successful calls do not modify this internally stored last-error code value.
  [RETVAL]
    The return value is the last-error code value. Functions set this value by calling the `SetLastProcessStatusError` function if they fail.

  To obtain an error string for system error codes, use the `FormatMessage` function. For a complete list of error codes, see the System Error Codes section in MSDN. There are pre-defined constants for the Win32 system error codes in the module <Win32API::Const>.

  You should call the `GetLastProcessStatusError` function immediately when a function's return value indicates that such a call will return useful data. A subsequent call to another ProcessStatus function could fail as well and `GetLastProcessStatusError` would return its error code instead of the former one.

  Function failure is typically indicated by a return value such as zero, undefined, or –1 (0xffffffff).

  Error codes returned are 32-bit values with the most significant bit set to 1 (bit 31 is the most significant bit). Zero code is `ERROR_SUCCESS`.

GetModuleBaseName($hProcess, $hModule, $lpBaseName, $nSize)
  Retrieves the base name of the specified module.
  hProcess [IN]
    Handle to the process that contains the module.

  hModule [IN]
    Handle to the module.

  lpBaseName [OUT]
    Reference to the buffer that receives the base name of the module. If the base name is longer than maximum number of characters specified by the `nSize` parameter, the base name is truncated.

  nSize [IN]
    Specifies the maximum number of characters to copy to the `lpBaseName` buffer. It defaults to `MAX_PATH` if omitted.

  [RETVAL]
    If the function succeeds, the return value specifies the length of the string copied to the buffer. If the function fails, the return value is zero. To get extended error information, call `GetLastProcessStatusError`.

GetModuleFileNameEx($hProcess, $hModule, $lpFilename, $nSize)
  Retrieves the fully qualified path for the specified module.
  hProcess [IN]
    Handle to the process that contains the module.

  hModule [IN]
    Handle to the module.

  lpFilename [OUT]
    Reference to the buffer that receives the fully qualified path to the module. If the file name is longer than maximum number of characters specified by the `nSize` parameter, the file name is truncated.

  nSize [IN]
    Specifies the maximum number of characters to copy to the `lpFilename` buffer. It defaults to `MAX_PATH` if omitted.

  [RETVAL]
    If the function succeeds, the return value specifies the length of the string copied to the buffer. If the function fails, the return value is zero. To get extended error information, call `GetLastProcessStatusError`.

GetModuleInformation($hProcess, $hModule, $lpmodinfo)
  Retrieves information about the specified module in the `MODULEINFO` structure.
  hProcess [IN]
    Handle to the process that contains the module.

  hModule [IN]
    Handle to the module.

  lpmodinfo [OUT]
    Reference to the `MODULEINFO` structure that receives information about the module.

  [RETVAL]
    If the function succeeds, the return value is nonzero. If the function fails, the return value is zero. To get extended error information, call `GetLastProcessStatusError`.

  (Obviously the parameter `cbSize` from the original Win32 function is omitted as there is no need to specify the size of the `MODULEINFO` structure returned as a hash in Perl.)

`SetLastProcessStatusError($dwError)`
  Sets the last-error code value of the ProcessStatus functions.
  dwError [IN]
    Specifies the last-error code.

  Error codes returned are 32-bit values with the most significant bit set to 1 (bit 31 is the most significant bit). Zero code is `ERROR_SUCCESS`.

  Applications can retrieve the value saved by this function by using the `GetLastProcessStatusError` function. The use of `GetLastProcessStatusError` is optional; an application can call it to find out the specific reason for a function failure.

# AUTHOR

Ferdinand Prantl <prantl@host.sk>

See http://prantl.host.sk/perl/modules/Win32API/ProcessStatus for the most recent version.

# COPYRIGHT

Copyright (c) 2002, Ferdinand Prantl. All rights reserved.

Permission to use, copy, modify, distribute and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. Author makes no representations about the suitability of this software for any purpose. It is provided ``as is'' without express or implied warranty.

# SEE ALSO

the Win32API::ToolHelp manpage, the Win32::Process manpage, the Win32::Job manpage and the Win32API::Const manpage.

Win32API::ProcessStatus - Perl extension for obtaining information about processes using the plain Win32 PSAPI