|
Win32API::ProcessStatus - Perl extension for obtaining information about processes using the plain Win32 PSAPI |
Win32API::ProcessStatus - Perl extension for obtaining information about processes using the plain Win32 PSAPI
use Win32API::ProcessStatus ':All';
# --- prints IDs of all processes
my $IDs;
EnumerateProceses($IDs);
foreach my $ID (@$IDs) {
print "$ID ";
}
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.)
Nothing is exported by default. The following tags can be used to have sets of symbols exported:
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.
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.
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.
4096 (1024 * sizeof(DWORD)) if omitted.
lpidProcess array. It can be
omitted if not needed.
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.
lphModule array. It defaults
to 4096 (1024 * sizeof(DWORD)) if omitted.
lphModule array. It can be omitted if not needed.
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()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.
nSize
parameter, the base name is truncated.
lpBaseName
buffer. It defaults to MAX_PATH if omitted.
GetLastProcessStatusError.
nSize parameter, the file name is truncated.
lpFilename
buffer. It defaults to MAX_PATH if omitted.
GetLastProcessStatusError.
MODULEINFO
structure.
MODULEINFO structure that receives information
about the module.
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)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.
Ferdinand Prantl <prantl@host.sk>
See http://prantl.host.sk/perl/modules/Win32API/ProcessStatus for the most recent version.
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.
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 |