Win32::Setupsup - Remote control for Windows applications
This document describes version 1.11 of Win32::Setupsup, released October 24, 2012
use Win32::Setupsup;
This module allows remote control of Windows programs. You can get window list, window properties and you can send keystroke to windows like VB's SendKey.
The Win32::CtrlGUI module provides a more user-friendly wrapper around this module.
The following constants are exported by default:
ERROR_TIMEOUT_ELAPSED VIF_CANNOTDELETE INVALID_PROPERTY_TYPE_ERROR VIF_CANNOTDELETECUR INVALID_SID_ERROR VIF_CANNOTREADDST NOT_ENOUGTH_MEMORY_ERROR VIF_CANNOTREADSRC UNKNOWN_PROPERTY_ERROR VIF_CANNOTRENAME VFFF_ISSHAREDFILE VIF_DIFFCODEPG VFF_BUFFTOOSMALL VIF_DIFFLANG VFF_CURNEDEST VIF_DIFFTYPE VFF_FILEINUSE VIF_FILEINUSE VFT2_DRV_COMM VIF_MISMATCH VFT2_DRV_DISPLAY VIF_OUTOFMEMORY VFT2_DRV_INPUTMETHOD VIF_OUTOFSPACE VFT2_DRV_INSTALLABLE VIF_SHARINGVIOLATION VFT2_DRV_KEYBOARD VIF_SRCOLD VFT2_DRV_LANGUAGE VIF_TEMPFILE VFT2_DRV_MOUSE VIF_WRITEPROT VFT2_DRV_NETWORK VOS_DOS VFT2_DRV_PRINTER VOS_DOS_WINDOWS16 VFT2_DRV_SOUND VOS_DOS_WINDOWS32 VFT2_DRV_SYSTEM VOS_NT VFT2_FONT_RASTER VOS_NT_WINDOWS32 VFT2_FONT_TRUETYPE VOS_OS216 VFT2_FONT_VECTOR VOS_OS216_PM16 VFT2_UNKNOWN VOS_OS232 VFT_APP VOS_OS232_PM32 VFT_DLL VOS_UNKNOWN VFT_DRV VOS__BASE VFT_FONT VOS__PM16 VFT_STATIC_LIB VOS__PM32 VFT_UNKNOWN VOS__WINDOWS16 VFT_VXD VOS__WINDOWS32 VIFF_DONTDELETEOLD VS_FF_DEBUG VIFF_FORCEINSTALL VS_FF_INFOINFERRED VIF_ACCESSVIOLATION VS_FF_PATCHED VIF_BUFFTOOSMALL VS_FF_PRERELEASE VIF_CANNOTCREATE VS_FF_PRIVATEBUILD VS_FF_SPECIALBUILD
The following functions are exported only by request:
SendKeys($window, $keystr, $activate, [$timeout]) EnumWindows(\@windows) EnumChildWindows($window, \\@childs) WaitForWindow($title, \$window, $timeout, [$refresh]) WaitForAnyWindow($title, \$window, $timeout, [$refresh]) WaitForAnyWindowAsynch($title, \$thread, \@actions, $timeout, [$refresh]) WaitForWindowClose($window, $timeout, [$refresh]) GetWindowText($window, \$windowtext) SetWindowText($window, $windowtext) GetDlgItem($window, $id, \$item) SetFocus($window) GetWindowProperties($window, @proptoget, \%windowprop) SetWindowProperties($window, \%windowprop) AccountToSid($server, $account, \$sid) SidToAccount($server, $sid, \$account) GetVersionInfo($filename, \%fileinfo) GetProcessList(\@proc, \@thread) KillProcess($proc, [$exitval, [$systemproc]]) Sleep([$time])
All of the functions return false if they fail. You can call Win32::Setupsup::GetLastError() to get more error information.
Note: the module defines some own error codes. You cannot call "net helpmsg" for a description and these errors are currently not exported.
SendKeys($window, $keystr, $activate, [$timeout])
Sends some key strokes to a window. $window must be a valid window handle or null. If $window is not valid the results are undefined. $keystr contains the keys to send. Some special keys are defined (see below). They must be enclosed in backslashes (you have to write two backslashes in perl). If you send alt, ctrl or shift down keys (f.e. \\alt+\\) don't forget the up key (\\alt-\\). If $activate is not null, $window will be activated everytime before a key will be sent. $timeout is the (optional) time between two key strokes. It's useful for debugging.
special keys:
ALT+ alt down ALT- alt up CTRL+ ctrl down CTRL- ctrl up SHIFT+ shift down SHIFT- shift up TAB tabulator RET return ESC escape BACK backspace DEL delete INS insert HELP help LEFT arrow left RIGHT arrow right UP arrow up DN arrow down PGUP page up PGDN page down BEG pos1 END end F1 function 1 ... F12 function 12 NUM0 0 on the num block ... NUM9 9 on the num block NUM* multiply key on the num block NUM+ add key on the num block NUM- minus key on the num block NUM/ divide key on the num block
EnumWindows(\@windows)
Enumerates all desktop windows on the screen and returns the handles in the @windows array. @windows must be an array reference.
EnumChildWindows($window, \\@childs)
Enumerates all child windows that belong to $window and returns the handles in the @childs array. $window must be a valid window handle @childs must be an array reference.
WaitForWindow($title, \$window, $timeout, [$refresh])
Waits for a window title and returns the app. window handle. Search is case insensitive. Returns if a window was found or $timeout elapsed (whatever happens earlier). $refresh is optional but you should specify a value (f.e. 100ms). Otherwise the function loops and consumes about 70 - 90% cpu time. If $timeout elapses GetLastError() returns ERROR_TIMEOUT_ELAPSED.
WaitForAnyWindow($title, \$window, $timeout, [$refresh])
Waits for a window title and returns the app. window handle. Search is case insensitive. $title could be a regular expression. Returns if a window was found or $timeout elapsed (whatever happens earlier). $refresh is optional but you should specify a value (f.e. 100ms). Otherwise the function loops and consumes about 70 - 90% cpu time. If $timeout elapses GetLastError() returns ERROR_TIMEOUT_ELAPSED.
WaitForAnyWindowAsynch($title, \$thread, \@actions, $timeout, [$refresh])
Creates a thread which waits for a window title. Function returns immediatly. If a app. window is catched, all actions defined in @actions will be applied. The thread handle is returned in $thread. $title could be a regular expression. Search is case insensitive. No actions are carried out if $timeout elapesed before a window was found. $refresh is optional but you should specify a value (f.e. 100ms). Otherwise the function loops and consumes about 70 - 90% cpu time.
The following actions are defined:
keys : sends key strokes to the window close : closes the window (sends a WM_CLOSE message) wait : simply waits kill : kills the process the window belongs to
WaitForWindowClose($window, $timeout, [$refresh])
Waits until a window will be closed. $window must be a valid window handle. Returns if $window is closed or $timeout elapsed (whatever happens earlier). $refresh is optional but you should specify a value (f.e. 100ms). Otherwise the function loops and consumes about 70 - 90% cpu time. If $timeout elapses GetLastError() returns ERROR_TIMEOUT_ELAPSED.
GetWindowText($window, \$windowtext)
Returns the caption of a window. $window must be a valid window handle and $windowtext a salar reference. There is no check if $window is valid. The function fail if there is not enougth memory. GetLastError() returns NOT_ENOUGTH_MEMORY_ERROR.
SetWindowText($window, $windowtext)
Sets the caption of a window. $window must be a valid window handle and $windowtext a salar value. You can use also SetWindowProp.
GetDlgItem($window, $id, \$item)
Gets the window handle of a dialog item. $window is the parent window and $id the id. $item contains the window handle if the function succeeds.
SetFocus($window)
Sets the focus to $window. It does not activate the window (the foreground application will not be changed if $windows belongs to another application).
GetWindowProperties($window, @proptoget, \%windowprop)
Gets the properties of a window. Specify all properties you wish in @proptoget. See the supported properties below. %windowprop will contain the properties on success. If you specify an unknown property GetLastError() returns UNKNOWN_PROPERTY_ERROR.
valid properties are:
checked : is window checked (checkboxes only) class : window class name classatom : class atom that $window belongs (see RegisterClass in win32 api) classbrush : handle to class background brush that $window belongs classcursor : handle to class cursor that $window belongs classicon : handle to class icon that $window belongs classiconsmall : handle to class small icon that $window belongs classmenu : handle to class menu that $window belongs classmodule : handle to class module that $window belongs classproc : pointer to class procedure that $window belongs classstyle : class style that $window belongs client : $window's client rectangle desktop : handle to desktop window dlgproc : pointer to $window's dialog procedure (if $window belongs to a dialog) enabled : is $window enabled or not extstyle : $window's extended style focused : is $window focused or not foreground : is $window the foreground window or not iconic : is $window iconic or not id : $window's id instance : application instance that $window belongs lastactivepopup : handle to the last active popup window owned by $window menu : handle to $window's menu next : handle to $window's next window in z order parent : handle to $window's parent window prev : handle to $window's previous window in z order pid : process id that $window belongs rect : $window's rectangle on the desktop style : $window's style text : $window's caption tid : thread id that $window belongs top : handle to $window's top window in z order unicode : is $window unicoded or not valid : is $window a valid window or not visible : is $window visible or not wndproc : pointer to $window's procedure zoomed : is $window zoomed or not
SetWindowProperties($window, \%windowprop)
Sets the properties of a window. Specify all properties you want to set in %windowprop. Some properties from GetWindowProperties cannot be set. These are:
class classatom classproc client desktop focused lastactivepopup pid tid unicode valid
If you specify some of them, they are ignored.
AccountToSid($server, $account, \$sid)
Converts an account name to a sid in a textual form (S-1-5-21- ...). The command will be executed on server $server. If $server is empty the local machine is used. If you need an account from a specific domain or server, you should specify domain\account or server\account. Otherwise the account will be resolved from trusted domains too. The first try will be made on $server. If it could not be resolved the next try is the domain $server belongs. After that all trusted domains will be tried. If you need a well known account (like system or everyone) don't specify a server or domain name. Otherwise the function will fail.
SidToAccount($server, $sid, \$account)
Converts a sid in a textual form to an account name. The command will be executed on server $server. If $server is empty the local machine is used.
GetVersionInfo($filename, \%fileinfo)
Gets the file information record stored in a file with version information. The following information will be retrieved:
FileVersionMS FileVersionLS ProductVersionMS ProductVersionLS FileFlagsMask FileFlags FileOS FileType FileSubtype FileDateMS FileDateLS Language Comments CompanyName FileDescription FileVersion InternalName LegalCopyright LegalTrademarks OriginalFilename PrivateBuild ProductName ProductVersion SpecialBuild
See also GetFileVersionInfo in Win32-SDK.
GetProcessList($server, \@proc, \@thread)
Gets all process and thread id's running on $server. $server must be a valid machine name or '' if you need data from the local machine. @proc contains the process id's and process names and @thread the thread id's and app. process index the tread belongs to. @proc and @thread are arrays. Each array element is a hash reference. To access the hash values see the example GetProcessList below.
KillProcess($proc, [$exitval, [$systemproc]])
Kills a process with pid $proc. The process ends with $exitval or 0 if omitted. If $systemproc is not null you can kill system processes too. But you need the app. rigths to do that (debug process must be enabled).
Sleep([$time])
Slepps $time milliseconds. If $time is omitted, your process sleeps forever.
CaptureMouse([$refresh])
Captures mouse pointer in the upper left corner. Mouse will be captured until UnCaptureMouse is called. Optionally, you can specify a refresh value. This means, every $refresh milliseconds the mouse pointer is moved to the upper left corner. Default is 100 ms.
UnCaptureMouse([$refresh])
Uncaptures a captured mouse pointer.
die if(!Win32::Setupsup::GetProcessList('', \@proc, \@threads)); foreach my $item (@proc) { print "name: ${$item}{'name'}; pid: ${$item}{'pid'}\n"; } foreach my $item (@threads) { print "tid: ${$item}{'tid'}; pidx: ${$item}{'process'}; " . "process: ${$proc[${$item}{'process'}]}{'name'}\n"; }
Win32::CtrlGUI, for a more user-friendly wrapper around this module.
Win32::Setupsup requires no configuration files or environment variables.
None reported.
No bugs have been reported.
Jens Helberg <jens.helberg AT de.bosch.com>
<jens.helberg AT de.bosch.com>
As of November 2011, Win32::Setupsup is now being maintained by Christopher J. Madsen <perl AT cjmweb.net>.
<perl AT cjmweb.net>
Please report any bugs or feature requests to <bug-Win32-Setupsup AT rt.cpan.org>, or through the web interface at http://rt.cpan.org/Public/Bug/Report.html?Queue=Win32-Setupsup
<bug-Win32-Setupsup AT rt.cpan.org>
You can follow or contribute to Win32::Setupsup's development at http://github.com/madsen/win32-setupsup.
Copyright 1999 by Jens Helberg
Copyright 2012 by Christopher J. Madsen
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
To install Win32::Setupsup, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Win32::Setupsup
CPAN shell
perl -MCPAN -e shell install Win32::Setupsup
For more information on module installation, please visit the detailed CPAN module installation guide.