This is Info file pm.info, produced by Makeinfo version 1.68 from the input file bigpm.texi.  File: pm.info, Node: Win32/FileSecurity, Next: Win32/GUI/BitmapInline, Prev: Win32/FileOp, Up: Module List manage FileSecurity Discretionary Access Control Lists in perl ************************************************************** NAME ==== Win32::FileSecurity - manage FileSecurity Discretionary Access Control Lists in perl SYNOPSIS ======== use Win32::FileSecurity; DESCRIPTION =========== This module offers control over the administration of system FileSecurity DACLs. You may want to use Get and EnumerateRights to get an idea of what mask values correspond to what rights as viewed from File Manager. CONSTANTS ========= DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER, SYNCHRONIZE, STANDARD_RIGHTS_REQUIRED, STANDARD_RIGHTS_READ, STANDARD_RIGHTS_WRITE, STANDARD_RIGHTS_EXECUTE, STANDARD_RIGHTS_ALL, SPECIFIC_RIGHTS_ALL, ACCESS_SYSTEM_SECURITY, MAXIMUM_ALLOWED, GENERIC_READ, GENERIC_WRITE, GENERIC_EXECUTE, GENERIC_ALL, F, FULL, R, READ, C, CHANGE FUNCTIONS ========= NOTE: ----- All of the functions return FALSE (0) if they fail, unless otherwise noted. Errors returned via $! containing both Win32 GetLastError() and a text message indicating Win32 function that failed. constant( $name, $set ) Stores the value of named constant $name into $set. Same as `$set = Win32::FileSecurity::NAME_OF_CONSTANT();'. Get( $filename, \%permisshash ) Gets the DACLs of a file or directory. Set( $filename, \%permisshash ) Sets the DACL for a file or directory. EnumerateRights( $mask, \@rightslist ) Turns the bitmask in $mask into a list of strings in @rightslist. MakeMask( qw( DELETE READ_CONTROL ) ) Takes a list of strings representing constants and returns a bitmasked integer value. %permisshash ------------ Entries take the form $permisshash{USERNAME} = $mask ; EXAMPLE1 ======== # Gets the rights for all files listed on the command line. use Win32::FileSecurity qw(Get EnumerateRights); foreach( @ARGV ) { next unless -e $_ ; if ( Get( $_, \%hash ) ) { while( ($name, $mask) = each %hash ) { print "$name:\n\t"; EnumerateRights( $mask, \@happy ) ; print join( "\n\t", @happy ), "\n"; } } else { print( "Error #", int( $! ), ": $!" ) ; } } EXAMPLE2 ======== # Gets existing DACL and modifies Administrator rights use Win32::FileSecurity qw(MakeMask Get Set); # These masks show up as Full Control in File Manager $file = MakeMask( qw( FULL ) ); $dir = MakeMask( qw( FULL GENERIC_ALL ) ); foreach( @ARGV ) { s/\\$//; next unless -e; Get( $_, \%hash ) ; $hash{Administrator} = ( -d ) ? $dir : $file ; Set( $_, \%hash ) ; } COMMON MASKS FROM CACLS AND WINFILE =================================== READ ---- MakeMask( qw( FULL ) ); # for files MakeMask( qw( READ GENERIC_READ GENERIC_EXECUTE ) ); # for directories CHANGE ------ MakeMask( qw( CHANGE ) ); # for files MakeMask( qw( CHANGE GENERIC_WRITE GENERIC_READ GENERIC_EXECUTE ) ); # for directories ADD & READ ---------- MakeMask( qw( ADD GENERIC_READ GENERIC_EXECUTE ) ); # for directories only! FULL ---- MakeMask( qw( FULL ) ); # for files MakeMask( qw( FULL GENERIC_ALL ) ); # for directories RESOURCES ========= From Microsoft: check_sd http://premium.microsoft.com/download/msdn/samples/2760.exe (thanks to Guert Schimmel at Sybase for turning me on to this one) VERSION ======= 1.03 ALPHA 97-12-14 REVISION NOTES ============== 1. ALPHA 1998.01.11 Imported diffs from 0.67 (parent) version 2. ALPHA 1997.12.14 Pod fixes, @EXPORT list additions Fix unitialized vars on unknown ACLs 3. ALPHA 1997.04.25 CORE Win32 version imported from 0.66 4. ALPHA 1997.07.07 Kludged bug in mapping bits to separate ACE's. Notably, this screwed up CHANGE access by leaving out a delete bit in the `INHERIT_ONLY_ACE | OBJECT_INHERIT_ACE' Access Control Entry. May need to rethink... 5. ALPHA 1997.03.13 Fixed bug in memory allocation check 6. ALPHA 1997.02.25 Tested with 5.003 build 303 Added ISA exporter, and @EXPORT_OK Added F, FULL, R, READ, C, CHANGE as composite pre-built mask names. Added server\ to keys returned in hash from Get Made constants and MakeMask case insensitive (I don't know why I did that) Fixed mask comparison in ListDacl and Enumerate Rights from simple & mask to exact bit match ! ( ( x & y ) ^ x ) makes sure all bits in x are set in y Fixed some "wild" pointers 7. ALPHA 1996.07.31 Now suitable for file and directory permissions Included ListDacl.exe in bundle for debugging Added "intuitive" inheritance for directories, basically functions like FM triggered by presence of GENERIC_ rights this may need to change see EXAMPLE2 Changed from AddAccessAllowedAce to AddAce for control over inheritance 8. ALPHA 1996.07.20 Fixed memory allocation bug 9. ALPHA 1996.07.29 Base functionality Using AddAccessAllowedAce Suitable for file permissions KNOWN ISSUES / BUGS =================== 1. May not work on remote drives. 2. Errors croak, don't return via $! as documented.  File: pm.info, Node: Win32/GUI/BitmapInline, Next: Win32/GUI/GridLayout, Prev: Win32/FileSecurity, Up: Module List Inline bitmap support for Win32::GUI ************************************ NAME ==== Win32::GUI::BitmapInline - Inline bitmap support for Win32::GUI SYNOPSIS ======== To create a BitmapInline: perl -MWin32::GUI::BitmapInline -e inline('image.bmp') >>script.pl To use a BitmapInline (in script.pl): use Win32::GUI; use Win32::GUI::BitmapInline (); $Bitmap1 = new Win32::GUI::BitmapInline( q( Qk32AAAAAAAAAHYAAAAoAAAAEAAAABAAAAABAAQAAAAAAIAAAAAAAAAAAAAAABAAAAAQAAAAAAAA AACcnABjzs4A9/f3AJzO/wCc//8Azv//AP///wD///8A////AP///wD///8A////AP///wD///8A ////AHd3d3d3d3d3d3d3d3d3d3dwAAAAAAAABxIiIiIiIiIHFkVFRUVEQgcWVVRUVFRCBxZVVVVF RUIHFlVVVFRUUgcWVVVVVUVCBxZVVVVUVFIHFlVVVVVVQgcWZmZmZmZSBxIiIiIRERF3cTZlUQd3 d3d3EREQd3d3d3d3d3d3d3d3 ) ); DESCRIPTION =========== This module can be used to "inline" a bitmap file in your script, so that it doesn't need to be accompained by several external files (less hassle when you need to redistribute your script or move it to another location). The inline function is used to create an inlined bitmap resource; it will print on STDOUT the packed data including the lines of Perl needed to use the inlined bitmap resource; it is intended to be used as a one-liner whose output is appended to your script. The function takes the name of the bitmap file to inline as its first parameter; an additional, optional parameter can be given which will be the name of the bitmap object in the resulting scriptlet, eg: perl -MWin32::GUI::BitmapInline -e inline('image.bmp','IMAGE') $IMAGE = new Win32::GUI::BitmapInline( q( ... If no name is given, the resulting object name will be $Bitmap1 (the next ones $Bitmap2 , $Bitmap3 and so on). Note that the object returned by `new Win32::GUI::BitmapInline' is a regular Win32::GUI::Bitmap object. WARNINGS ======== * *Requires MIME::Base64* ...and, of course, Win32::GUI :-) *Don't use it on large bitmap files!* BitmapInline was designed for small bitmaps, such as toolbar items, icons, et alia; it is not at all performant. Inlined data takes approximatively the size of your bitmap file plus a 30%; thus, if you inline a 100k bitmap you're adding about 130k of bad-looking data to your script... *Your script must have write access to its current directory* When inlined data are used in your script (with `new Win32::GUI::BitmapInline...') a temporary file is created, then loaded as a regular bitmap and then immediately deleted. This will fail if your script is not able to create and delete files in the current directory at the moment of the call. One workaround could be to change directory to a safer place before constructing the bitmap: chdir("c:\\temp"); $Bitmap1 = new Win32::GUI::BitmapInline( ... ); A better solution could pop up in some future release... *The package exports inline by default* For practical reasons (see one-liners above), inline is exported by default into your main namespace; to avoid this side-effect is recommended to use the module in your production scripts as follows: use Win32::GUI::BitmapInline (); VERSION ======= Win32::GUI::BitmapInline version 0.01, 02 April 1999. AUTHOR ====== Aldo Calpini ( `dada@divinf.it' ).  File: pm.info, Node: Win32/GUI/GridLayout, Next: Win32/GuiTest, Prev: Win32/GUI/BitmapInline, Up: Module List Grid layout support for Win32::GUI ********************************** NAME ==== Win32::GUI::GridLayout - Grid layout support for Win32::GUI SYNOPSIS ======== use Win32::GUI:: use Win32::GUI::GridLayout; # 1. make a "static" grid $grid = new Win32::GUI::GridLayout(400, 300, 3, 3, 0, 0); $win = new Win32::GUI::Window( $win->AddLabel( -name => "label1", -text => "Label 1", -width => $grid->width(35), -height => $grid->height(11), -left => $grid->col(1, "left"), -top => $grid->row(1, "top"), ); # 2. make a "dynamic" grid $grid = apply Win32::GUI::GridLayout($win, 3, 3, 0, 0); $win->AddLabel( -name => "label1", -text => "Label 1", ); $grid->add($win->label1, 1, 1, "left top"); $grid->recalc(); DESCRIPTION =========== Constructors ------------ new Win32::GUI::GridLayout(WIDTH, HEIGHT, COLS, ROWS, XPAD, YPAD) apply Win32::GUI::GridLayout(WINDOW, COLS, ROWS, XPAD, YPAD) Methods ------- add(CONTROL, COL, ROW, ALIGN) Adds CONTROL to the grid at (COL, ROW). ALIGN can specify both horizontal and vertical alignment (see the col() and row() methods), separated by at least one blank and/or a comma. Example: $grid->add($win->label1, 1, 1, "left top"); col(N, ALIGN) Positions the control at the Nth column in the grid, optionally with an ALIGN; this can be feed to a `-left' option when creating a control. ALIGN can be left, center or right (can be shortened to l, c, r); default is left. Note that for alignment to work properly, the width() and height() methods must have been previously called. Example: $win->AddLabel( -name => "label1", -text => "Label 1", -width => $grid->width(35), -height => $grid->height(11), -left => $grid->col(1, "left"), -top => $grid->row(1, "top"), ); draw() Draws the GridLayout in the associated window (may be useful for debugging); is only meaningful if the GridLayout was created with the apply() constructor. height(N) Sets the height of the control for subsequent alignment; this can be feed to a `-height' option when creating a control. Example: see col(). recalc() Recalculates the grid and repositions all the add()ed controls, taking into account the actual window and controls sizes; is only meaningful if the GridLayout was created with the apply() constructor. Example: sub Window_Resize { $grid->recalc(); } row(N, ALIGN) Positions the control at the Nth row in the grid, optionally with an ALIGN; this can be feed to a `-top' option when creating a control. ALIGN can be top, center or `bottom' (can be shortened to t, c, b); default is top. Note that for alignment to work properly, the width() and height() methods must have been previously called. Example: see col(). width(N) Sets the width of the control for subsequent alignment; this can be feed to a `-width' option when creating a control. Example: see col(). VERSION ======= Win32::GUI::GridLayout version 0.03, 13 April 1999. AUTHOR ====== Mike Kangas ( `kangas@anlon.com' ); additional coding by Aldo Calpini ( `dada@divinf.it' ).  File: pm.info, Node: Win32/GuiTest, Next: Win32/IPC, Prev: Win32/GUI/GridLayout, Up: Module List Perl GUI Test Utilities *********************** NAME ==== Win32::GuiTest - Perl GUI Test Utilities SYNOPSIS ======== use Win32::GuiTest qw(FindWindowLike GetWindowText SetForegroundWindow SendKeys); $Win32::GuiTest::debug = 0; # Set to "1" to enable verbose mode my @windows = FindWindowLike(0, "^Microsoft Excel", "^XLMAIN\$"); for (@windows) { print "$_>\t'", GetWindowText($_), "'\n"; SetForegroundWindow($_); SendKeys("%fn~a{TAB}b{TAB}{BS}{DOWN}"); } INSTALLATION ============ perl makefile.pl nmake nmake test nmake install If you're using ActivePerl 5.6 (http://www.activestate.com/Products/ActivePerl/index.html) you can install the binary package I'm including instead. You'll need to enter PPM (Perl Package Manager) from the command-line. Once you have extracted the files I send you to a directory of your machine, enter PPM and do like this: C:\TEMP>ppm PPM interactive shell (2.0) - type 'help' for available commands. PPM> install C:\temp\win32-guitest.ppd Install package 'C:\temp\win32-guitest.ppd?' (y/N): Y Retrieving package 'C:\temp\win32-guitest.ppd'... Writing C:\Perl\site\lib\auto\Win32\GuiTest\.packlist PPM> I extracted them to 'c:\temp', please use the directory where you extracted the files instead. DESCRIPTION =========== Most GUI test scripts I have seen/written for Win32 use some variant of Visual Basic (e.g. MS-VB or MS-Visual Test). The main reason is the availability of the SendKeys function. A nice way to drive Win32 programs from a test script is to use OLE Automation (ActiveX Scripting), but not all Win32 programs support this interface. That's where SendKeys comes handy. Some time ago Al Williams published a Delphi version in Dr. Dobb's (http://www.ddj.com/ddj/1997/careers1/wil2.htm). I ported it to C and packaged it using h2xs... The tentative name for this module is Win32::GuiTest (mostly because I plan to include more GUI testing functions). VERSION ======= 0.09 CHANGES ======= 0.01 Wed Aug 12 21:58:13 1998 - original version; created by h2xs 1.18 0.02 Sun Oct 25 20:18:17 1998 - Added several Win32 API functions (typemap courtesy of Win32::APIRegistry): SetForegroundWindow GetDesktopWindow GetWindow GetWindowText GetClassName GetParent GetWindowLong SetFocus - Ported FindWindowLike (MS-KB, Article ID: Q147659) from VB to Perl. Instead of using "like", I used Perl regexps. Why didn't Jeffrey Friedl include VB in "Mastering Regular Expressions"? ;-). 0.03 Sun Oct 31 18:31:52 1999 - Perhaps first version released thru CPAN (user: erngui). - Changed name from Win32::Test to Win32::GuiTest - Fixed bug: using strdup resulted in using system malloc and perl's free, resulting in a runtime error. This way we always use perl's malloc. Got the idea from 'ext\Dynaloader\dl_aix.xs:calloc'. 0.04 Fri Jan 7 17:44:00 2000 - Fixed Compatibility with ActivePerl 522. Thanks to Johannes Maehner for the initial patch. There were two main issues: /1/ ActivePerl (without CAPI=TRUE) compiles extensions in C++ mode (some casts from void*, etc.. were needed). /2/ The old typemap + buffers.h I was using had been rendered incompatible by changes in ActivePerl. As the incompatible typemaps were redundant, I deleted them. Now it works on ActivePerl (both using 'perl makefile.pl' and 'perl makefile.pl CAPI=TRUE') and on CPAN perl (http://www.perl.com/CPAN/src/stable.zip). - As requests for changes keep comming in, I've decided to put it all under version control (cvs if you're curious about it). 0.05 Sat Mar 11 23:11:42 2000 - Added support for sending function keys (e.g. "%{F4}"). A new test script is added to the distribution (eg\notepad.pl) to test this functionality. - Code cleanup to make adding new keywords easier. 0.06 Sun Mar 12 01:51:18 2000 - Added support for sending mouse events. Thanks to Ben Shern for the idea and original code. Also added 'eg\paint.pl' to the distribution to test this functionality. - Code cleanup. 0.07 Sun Nov 19 13:02:00 2000 - Added MouseMoveAbsPix to allow moving the mouse to an absolute pixel coordinate instead of using mouse_event's (0, 0) to (65535, 65535) coordinates. Thanks to Phill Wolf for the idea and original code. Also added 'eg\paint_abs.pl' to the distribution to test this functionality. - Added binaries for the ActivePerl distribution. 0.08 Sun Dec 17 19:33:07 2000 - Added WMGetText to allow getting the content of an EDIT window. See 'eg\notepad_text.pl' for more details. Thanks to Mauro from Italy for the idea. 0.09 Thu Jan 4 22:30:50 2001 - Added {SPC} action to sendkeys to simulate hitting the spacebar. Thanks to Sohrab Niramwalla for the idea. =cut package Win32::GuiTest; use strict; use vars qw($VERSION @ISA @EXPORT @EXPORT_OK $debug); require Exporter; require DynaLoader; require AutoLoader; @ISA = qw(Exporter DynaLoader); # Items to export into callers namespace by default. Note: do not export # names by default without a very good reason. Use EXPORT_OK instead. # Do not simply export all your public functions/methods/constants. @EXPORT = qw( ); @EXPORT_OK = qw(SendKeys FindWindowLike SetForegroundWindow GetDesktopWindow GetWindow GetWindowText GetClassName GetParent GetWindowID GetWindowLong $debug SendMouse SendLButtonUp SendLButtonDown SendMButtonUp SendMButtonDown SendRButtonUp SendRButtonDown SendMouseMoveAbs MouseMoveAbsPix SendMouseMoveRel WMGetKey); $VERSION = '0.9'; $debug = 0; bootstrap Win32::GuiTest $VERSION; sub GWL_ID { -12; } sub GW_HWNDNEXT { 2; } sub GW_CHILD { 5; } FUNCTIONS ========= $debug When set enables the verbose mode. SendKeys KEYS Sends keystrokes to the active window as if typed at the keyboard. The keystrokes to send are specified in KEYS. There are several characters that have special meaning. This allows sending control codes and modifiers: ~ means ENTER + means SHIFT ^ means CTRL % means ALT The parens allow character grouping. You may group several characters, so that a specific keyboard modifier applies to all of them. E.g. SendKeys("ABC") <=> SendKeys("+(abc)") The curly braces are used to quote special characters (SendKeys("{+}{{}") sends a '+' and a '{'). You can also use them to specify certain named actions: Name Action {BACKSPACE} Backspace {BS} Backspace {BKSP} Backspace {BREAK} Break {CAPS} Caps Lock {DELETE} Delete {DOWN} Down arrow {END} End {ENTER} Enter (same as ~) {ESCAPE} Escape {HELP} Help key {HOME} Home {INSERT} Insert {LEFT} Left arrow {NUMLOCK} Num lock {PGDN} Page down {PGUP} Page up {PRTSCR} Print screen {RIGHT} Right arrow {SCROLL} Scroll lock {TAB} Tab {UP} Up arrow {PAUSE} Pause {F1} Function Key 1 ... ... {F24} Function Key 24 {SPC} Spacebar {SPACE} Spacebar {SPACEBAR} Spacebar All these named actions take an optional integer argument, like in {RIGHT 5}. For all of them, except PAUSE, the argument means a repeat count. For PAUSE it means the number of milliseconds SendKeys should pause before proceding. In this implementation, SendKeys always returns after sending the keystrokes. There is no way to tell if an application has processed those keys when the function returns. SendMouse COMMAND This function emulates mouse input. The COMMAND parameter is a string containing one or more of the following substrings: {LEFTDOWN} left button down {LEFTUP} left button up {MIDDLEDOWN} middle button down {MIDDLEUP} middle button up {RIGHTDOWN} right button down {RIGHTUP} right button up {LEFTCLICK} left button single click {MIDDLECLICK} middle button single click {RIGHTCLICK} right button single click {ABSx,y} move to absolute coordinate ( x, y ) {RELx,y} move to relative coordinate ( x, y ) Note: Absolute mouse coordinates range from 0 to 65535. Relative coordinates can be positive or negative. If you need pixel coordinates you can use MouseMoveAbsPix. Also equivalent low-level functions are available: SendLButtonUp() SendLButtonDown() SendMButtonUp() SendMButtonDown() SendRButtonUp() SendRButtonDown() SendMouseMoveRel(x,y) SendMouseMoveAbs(x,y) =back MouseMoveAbsPix(X,Y) Move the mouse cursor to the screen pixel indicated as parameter. # Moves to x=200, y=100 in pixel coordinates. MouseMoveAbsPix(200, 100); FindWindowLike WINDOW, TITLEPATTERN, CLASSPATTERN, CHILDID Finds the window handles of the windows matching the specified parameters and returns them as a list. You may specify the handle of the window to search under. The routine searches through all of this windows children and their children recursively. If 'undef' then the routine searches through all windows. There is also a regexp used to match against the text in the window caption and another regexp used to match against the text in the window class. If you pass a child ID number, the functions will only match windows with this id. In each case undef matches everything. COPYRIGHT ========= The SendKeys function is based on the Delphi sourcecode published by Al Williams (http://www.al-williams.com/awc/) in Dr.Dobbs (http://www.ddj.com/ddj/1997/careers1/wil2.htm). Copyright (c) 1998-2001 Ernesto Guisado. All rights reserved. This program is free software; You may distribute it and/or modify it under the same terms as Perl itself. AUTHOR ====== Ernesto Guisado ,  File: pm.info, Node: Win32/IPC, Next: Win32/Internet, Prev: Win32/GuiTest, Up: Module List Base class for Win32 synchronization objects ******************************************** NAME ==== Win32::IPC - Base class for Win32 synchronization objects SYNOPSIS ======== use Win32::Event 1.00 qw(wait_any); #Create objects. wait_any(@ListOfObjects,$timeout); DESCRIPTION =========== This module is loaded by the other Win32 synchronization modules. You shouldn't need to load it yourself. It supplies the wait functions to those modules. The synchronization modules are `"Win32::ChangeNotify"' in this node, `"Win32::Event"' in this node, `"Win32::Mutex"' in this node, & `"Win32::Semaphore"' in this node. Methods ------- *Win32::IPC* supplies one method to all synchronization objects. $obj->wait([$timeout]) Waits for $obj to become signalled. $timeout is the maximum time to wait (in milliseconds). If $timeout is omitted, waits forever. If $timeout is 0, returns immediately. Returns: +1 The object is signalled -1 The object is an abandoned mutex 0 Timed out undef An error occurred Functions --------- wait_any(@objects, [$timeout]) Waits for at least one of the `@objects' to become signalled. $timeout is the maximum time to wait (in milliseconds). If $timeout is omitted, waits forever. If $timeout is 0, returns immediately. The return value indicates which object ended the wait: +N $object[N-1] is signalled -N $object[N-1] is an abandoned mutex 0 Timed out undef An error occurred If more than one object became signalled, the one with the lowest index is used. wait_all(@objects, [$timeout]) This is the same as `wait_any', but it waits for all the `@objects' to become signalled. The return value indicates the last object to become signalled, and is negative if at least one of the `@objects' is an abandoned mutex. Deprecated Functions and Methods -------------------------------- *Win32::IPC* still supports the ActiveWare syntax, but its use is deprecated. INFINITE Constant value for an infinite timeout. Omit the $timeout argument instead. WaitForMultipleObjects(\@objects, $wait_all, $timeout) Warning: `WaitForMultipleObjects' erases `@objects'! Use `wait_all' or `wait_any' instead. $obj->Wait($timeout) Similar to `not $obj->wait($timeout)'. AUTHOR ====== Christopher J. Madsen <`chris_madsen@geocities.com'> Loosely based on the original module by ActiveWare Internet Corp., `http://www.ActiveWare.com'  File: pm.info, Node: Win32/Internet, Next: Win32/Mutex, Prev: Win32/IPC, Up: Module List Access to WININET.DLL functions ******************************* NAME ==== Win32::Internet - Access to WININET.DLL functions INTRODUCTION ============ This extension to Perl implements the Win32 Internet APIs (found in `WININET.DLL'). They give a complete support for HTTP, FTP and GOPHER connections. See the `"Version History"' in this node and the `"Functions Table"' in this node for a list of the currently supported features. You should also get a copy of the `"Microsoft Win32 Internet Functions"' in this node documentation. REFERENCE ========= To use this module, first add the following line at the beginning of your script: use Win32::Internet; Then you have to open an Internet connection with this command: $Connection = new Win32::Internet(); This is required to use any of the function of this module. It will create an Internet object in Perl on which you can act upon with the `"General Internet Functions"' in this node explained later. The objects available are: * Internet connections (the main object, see new) * URLs (see OpenURL) * FTP sessions (see FTP) * HTTP sessions (see HTTP) * HTTP requests (see OpenRequest) As in the good Perl tradition, there are in this extension different ways to do the same thing; there are, in fact, different levels of implementation of the Win32 Internet Functions. Some routines use several Win32 API functions to perform a complex task in a single call; they are simpler to use, but of course less powerful. There are then other functions that implement nothing more and nothing less than the corresponding API function, so you can use all of their power, but with some additional programming steps. To make an example, there is a function called FetchURL that you can use to fetch the content of any HTTP, FTP or GOPHER URL with this simple commands: $INET = new Win32::Internet(); $file = $INET->FetchURL("http://www.yahoo.com"); You can have the same result (and this is actually what is done by FetchURL) this way: $INET = new Win32::Internet(); $URL = $INET->OpenURL("http://www.yahoo.com"); $file = $URL->ReadFile(); $URL->Close(); Or, you can open a complete HTTP session: $INET = new Win32::Internet(); $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it"); ($statuscode, $headers, $file) = $HTTP->Request("/"); $HTTP->Close(); Finally, you can choose to manage even the HTTP request: $INET = new Win32::Internet(); $HTTP = $INET->HTTP("www.yahoo.com", "anonymous", "dada@divinf.it"); $HTTP->OpenRequest($REQ, "/"); $REQ->AddHeader("If-Modified-Since: Saturday, 16-Nov-96 15:58:50 GMT"); $REQ->SendRequest(); $statuscode = $REQ->QueryInfo("",HTTP_QUERY_STATUS_CODE); $lastmodified = $REQ->QueryInfo("Last-Modified"); $file = $REQ->ReadEntireFile(); $REQ->Close(); $HTTP->Close(); To open and control a complete FTP session, type: $Connection->FTP($Session, "ftp://ftp.activeware.com", "anonymous", "dada\@divinf.it"); This will create an FTP object in Perl to which you can apply the `"FTP functions"' in this node provided by the package: $Session->Cd("/ntperl/perl5.001m/CurrentBuild"); $Session->Ascii(); $Session->Get("110-i86.zip"); $Session->Close(); For a more complete example, see the TEST.PL file that comes with the package. General Internet Functions -------------------------- *General Note* All methods assume that you have the line: use Win32::Internet; somewhere before the method calls, and that you have an Internet object called $INET which was created using this call: $INET = new Win32::Internet(); See new for more information. Methods CanonicalizeURL URL, [flags] Converts a URL to a canonical format, which includes converting unsafe characters to escape sequences. Returns the canonicalized URL or undef on errors. For the possible values of flags, refer to the `"Microsoft Win32 Internet Functions"' in this node document. See also CombineURL and OpenURL. Example: $cURL = $INET->CanonicalizeURL($URL); $URL = $INET->CanonicalizeURL($cURL, ICU_DECODE); Close Close object Closes an Internet connection. This can be applied to any Win32::Internet object (Internet connections, URLs, FTP sessions, etc.). Note that it is not "strictly" required to close the connections you create, since the Win32::Internet objects are automatically closed when the program ends (or when you elsehow destroy such an object). Example: $INET->Close(); $FTP->Close(); $INET->Close($FTP); # same as above... CombineURL baseURL, relativeURL, [flags] Combines a base and relative URL into a single URL. Returns the (canonicalized) combined URL or undef on errors. For the possible values of flags, refer to the `"Microsoft Win32 Internet Functions"' in this node document. See also CombineURL and OpenURL. Example: $URL = $INET->CombineURL("http://www.divinf.it/dada/perl/internet", ".."); ConnectBackoff [value] Reads or sets the delay value, in milliseconds, to wait between connection retries. If no value parameter is specified, the current value is returned; otherwise, the delay between retries is set to value. See also ConnectTimeout, ConnectRetries, QueryOption and SetOption. Example: $HTTP->ConnectBackoff(2000); $backoff = $HTTP->ConnectBackoff(); ConnectRetries [value] Reads or sets the number of times a connection is retried before considering it failed. If no value parameter is specified, the current value is returned; otherwise, the number of retries is set to value. The default value for ConnectRetries is 5. See also ConnectBackoff, ConnectTimeout, QueryOption and SetOption. Example: $HTTP->ConnectRetries(20); $retries = $HTTP->ConnectRetries(); ConnectTimeout [value] Reads or sets the timeout value (in milliseconds) before a connection is considered failed. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for ConnectTimeout is infinite. See also ConnectBackoff, ConnectRetries, QueryOption and SetOption. Example: $HTTP->ConnectTimeout(10000); $timeout = $HTTP->ConnectTimeout(); ControlReceiveTimeout [value] Reads or sets the timeout value (in milliseconds) to use for non-data (control) receive requests before they are canceled. Currently, this value has meaning only for FTP sessions. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for ControlReceiveTimeout is infinite. See also ControlSendTimeout, QueryOption and SetOption. Example: $HTTP->ControlReceiveTimeout(10000); $timeout = $HTTP->ControlReceiveTimeout(); ControlSendTimeout [value] Reads or sets the timeout value (in milliseconds) to use for non-data (control) send requests before they are canceled. Currently, this value has meaning only for FTP sessions. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for ControlSendTimeout is infinite. See also ControlReceiveTimeout, QueryOption and SetOption. Example: $HTTP->ControlSendTimeout(10000); $timeout = $HTTP->ControlSendTimeout(); CrackURL URL, [flags] Splits an URL into its component parts and returns them in an array. Returns undef on errors, otherwise the array will contain the following values: *scheme, host, port, username, password, path, extrainfo*. For example, the URL "http://www.divinf.it/index.html#top" can be splitted in: http, www.divinf.it, 80, anonymous, dada@divinf.it, /index.html, #top If you don't specify a flags parameter, ICU_ESCAPE will be used by default; for the possible values of flags refer to the `"Microsoft Win32 Internet Functions"' in this node documentation. See also CreateURL. Example: @parts=$INET->CrackURL("http://www.activeware.com"); ($scheme, $host, $port, $user, $pass, $path, $extra) = $INET->CrackURL("http://www.divinf.it:80/perl-win32/index.sht#feedback"); CreateURL scheme, hostname, port, username, password, path, extrainfo, [flags] CreateURL hashref, [flags] Creates a URL from its component parts. Returns undef on errors, otherwise the created URL. If you pass *hashref* (a reference to an hash array), the following values are taken from the array: %hash=( "scheme" => "scheme", "hostname" => "hostname", "port" => port, "username" => "username", "password" => "password", "path" => "path", "extrainfo" => "extrainfo", ); If you don't specify a flags parameter, ICU_ESCAPE will be used by default; for the other possible values of flags refer to the `"Microsoft Win32 Internet Functions"' in this node documentation. See also CrackURL. Example: $URL=$I->CreateURL("http", "www.divinf.it", 80, "", "", "/perl-win32/index.sht", "#feedback"); $URL=$I->CreateURL(\%params); DataReceiveTimeout [value] Reads or sets the timeout value (in milliseconds) to use for data receive requests before they are canceled. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for DataReceiveTimeout is infinite. See also DataSendTimeout, QueryOption and SetOption. Example: $HTTP->DataReceiveTimeout(10000); $timeout = $HTTP->DataReceiveTimeout(); DataSendTimeout [value] Reads or sets the timeout value (in milliseconds) to use for data send requests before they are canceled. If no value parameter is specified, the current value is returned; otherwise, the timeout is set to value. The default value for DataSendTimeout is infinite. See also DataReceiveTimeout, QueryOption and SetOption. Example: $HTTP->DataSendTimeout(10000); $timeout = $HTTP->DataSendTimeout(); Error Returns the last recorded error in the form of an array or string (depending upon the context) containing the error number and an error description. Can be applied on any Win32::Internet object (FTP sessions, etc.). There are 3 types of error you can encounter; they are recognizable by the error number returned: * -1 A "trivial" error has occurred in the package. For example, you tried to use a method on the wrong type of object. * 1 .. 11999 A generic error has occurred and the Win32::GetLastError error message is returned. * 12000 and higher An Internet error has occurred; the extended Win32 Internet API error message is returned. See also GetResponse. Example: die $INET->Error(), qq(\n); ($ErrNum, $ErrText) = $INET->Error(); FetchURL URL Fetch the content of an HTTP, FTP or GOPHER URL. Returns the content of the file read (or undef if there was an error and nothing was read). See also OpenURL and ReadFile. Example: $file = $INET->FetchURL("http://www.yahoo.com/"); $file = $INET->FetchURL("ftp://www.activeware.com/contrib/internet.zip"); FTP ftpobject, server, username, password, [port, pasv, context] FTP ftpobject, hashref Opens an FTP connection to server logging in with the given username and password. The parameters and their values are: * server The server to connect to. Default: none. * username The username used to login to the server. Default: anonymous. * password The password used to login to the server. Default: none. * port The port of the FTP service on the server. Default: 21. * pasv If it is a value other than 0, use passive transfer mode. Default is taken from the parent Internet connection object; you can set this value with the Pasv method. * context A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Default: none. If you pass *hashref* (a reference to an hash array), the following values are taken from the array: %hash=( "server" => "server", "username" => "username", "password" => "password", "port" => port, "pasv" => pasv, "context" => context, ); This method returns undef if the connection failed, a number otherwise. You can then call any of the `"FTP functions"' in this node as methods of the newly created *ftpobject*. Example: $result = $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it"); # and then for example... $FTP->Cd("/ntperl/perl5.001m/CurrentBuild"); $params{"server"} = "ftp.activeware.com"; $params{"password"} = "dada\@divinf.it"; $params{"pasv"} = 0; $result = $INET->FTP($FTP,\%params); GetResponse Returns the text sent by a remote server in response to the last function executed. It applies on any Win32::Internet object, particularly of course on `FTP sessions|"FTP functions"' in this node. See also the Error function. Example: print $INET->GetResponse(); $INET->FTP($FTP, "ftp.activeware.com", "anonymous", "dada\@divinf.it"); print $FTP->GetResponse(); GetStatusCallback context Returns information about the progress of the asynchronous operation identified by context; those informations consist of two values: a status code (one of the INTERNET_STATUS_* `"Constants"' in this node) and an additional value depending on the status code; for example, if the status code returned is INTERNET_STATUS_HANDLE_CREATED, the second value will hold the handle just created. For more informations on those values, please refer to the `"Microsoft Win32 Internet Functions"' in this node documentation. See also SetStatusCallback. Example: ($status, $info) = $INET->GetStatusCallback(1); HTTP httpobject, server, username, password, [port, flags, context] HTTP httpobject, hashref Opens an HTTP connection to server logging in with the given username and password. The parameters and their values are: * server The server to connect to. Default: none. * username The username used to login to the server. Default: anonymous. * password The password used to login to the server. Default: none. * port The port of the HTTP service on the server. Default: 80. * flags Additional flags affecting the behavior of the function. Default: none. * context A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Default: none. Refer to the `"Microsoft Win32 Internet Functions"' in this node documentation for more details on those parameters. If you pass *hashref* (a reference to an hash array), the following values are taken from the array: %hash=( "server" => "server", "username" => "username", "password" => "password", "port" => port, "flags" => flags, "context" => context, ); This method returns undef if the connection failed, a number otherwise. You can then call any of the `"HTTP functions"' in this node as methods of the newly created *httpobject*. Example: $result = $INET->HTTP($HTTP,"www.activeware.com","anonymous","dada\@divinf.it"); # and then for example... ($statuscode, $headers, $file) = $HTTP->Request("/gifs/camel.gif"); $params{"server"} = "www.activeware.com"; $params{"password"} = "dada\@divinf.it"; $params{"flags"} = INTERNET_FLAG_RELOAD; $result = $INET->HTTP($HTTP,\%params); new Win32::Internet [useragent, opentype, proxy, proxybypass, flags] new Win32::Internet [hashref] Creates a new Internet object and initializes the use of the Internet functions; this is required before any of the functions of this package can be used. Returns undef if the connection fails, a number otherwise. The parameters and their values are: * useragent The user agent passed to HTTP requests. See OpenRequest. Default: Perl-Win32::Internet/version. * opentype How to access to the Internet (eg. directly or using a proxy). Default: INTERNET_OPEN_TYPE_DIRECT. * proxy Name of the proxy server (or servers) to use. Default: none. * proxybypass Optional list of host names or IP addresses, or both, that are known locally. Default: none. * flags Additional flags affecting the behavior of the function. Default: none. Refer to the `"Microsoft Win32 Internet Functions"' in this node documentation for more details on those parameters. If you pass *hashref* (a reference to an hash array), the following values are taken from the array: %hash=( "useragent" => "useragent", "opentype" => "opentype", "proxy" => "proxy", "proxybypass" => "proxybypass", "flags" => flags, ); Example: $INET = new Win32::Internet(); die qq(Cannot connect to Internet...\n) if ! $INET; $INET = new Win32::Internet("Mozilla/3.0", INTERNET_OPEN_TYPE_PROXY, "www.microsoft.com", ""); $params{"flags"} = INTERNET_FLAG_ASYNC; $INET = new Win32::Internet(\%params); OpenURL urlobject, URL Opens a connection to an HTTP, FTP or GOPHER Uniform Resource Location (URL). Returns undef on errors or a number if the connection was succesful. You can then retrieve the URL content by applying the methods QueryDataAvailable and ReadFile on the newly created *urlobject*. See also FetchURL. Example: $INET->OpenURL($URL, "http://www.yahoo.com/"); $bytes = $URL->QueryDataAvailable(); $file = $URL->ReadEntireFile(); $URL->Close(); Password [password] Reads or sets the password used for an FTP or HTTP connection. If no password parameter is specified, the current value is returned; otherwise, the password is set to password. See also Username, QueryOption and SetOption. Example: $HTTP->Password("splurfgnagbxam"); $password = $HTTP->Password(); QueryDataAvailable Returns the number of bytes of data that are available to be read immediately by a subsequent call to ReadFile (or undef on errors). Can be applied to URL or HTTP request objects. See OpenURL or OpenRequest. Example: $INET->OpenURL($URL, "http://www.yahoo.com/"); $bytes = $URL->QueryDataAvailable(); QueryOption option Queries an Internet option. For the possible values of option, refer to the `"Microsoft Win32 Internet Functions"' in this node document. See also SetOption. Example: $value = $INET->QueryOption(INTERNET_OPTION_CONNECT_TIMEOUT); $value = $HTTP->QueryOption(INTERNET_OPTION_USERNAME); ReadEntireFile Reads all the data available from an opened URL or HTTP request object. Returns what have been read or undef on errors. See also OpenURL, OpenRequest and ReadFile. Example: $INET->OpenURL($URL, "http://www.yahoo.com/"); $file = $URL->ReadEntireFile(); ReadFile bytes Reads bytes bytes of data from an opened URL or HTTP request object. Returns what have been read or undef on errors. See also OpenURL, OpenRequest, QueryDataAvailable and ReadEntireFile. Note: be careful to keep bytes to an acceptable value (eg. don't tell him to swallow megabytes at once...). ReadEntireFile in fact uses QueryDataAvailable and ReadFile in a loop to read no more than 16k at a time. Example: $INET->OpenURL($URL, "http://www.yahoo.com/"); $chunk = $URL->ReadFile(16000); SetOption option, value Sets an Internet option. For the possible values of option, refer to the `"Microsoft Win32 Internet Functions"' in this node document. See also QueryOption. Example: $INET->SetOption(INTERNET_OPTION_CONNECT_TIMEOUT,10000); $HTTP->SetOption(INTERNET_OPTION_USERNAME,"dada"); SetStatusCallback Initializes the callback routine used to return data about the progress of an asynchronous operation. Example: $INET->SetStatusCallback(); This is one of the step required to perform asynchronous operations; the complete procedure is: # use the INTERNET_FLAG_ASYNC when initializing $params{'flags'}=INTERNET_FLAG_ASYNC; $INET = new Win32::Internet(\%params); # initialize the callback routine $INET->SetStatusCallback(); # specify the context parameter (the last 1 in this case) $INET->HTTP($HTTP, "www.yahoo.com", "anonymous", "dada\@divinf.it", 80, 0, 1); At this point, control returns immediately to Perl and $INET->Error() will return 997, which means an asynchronous I/O operation is pending. Now, you can call $HTTP->GetStatusCallback(1); in a loop to verify what's happening; see also GetStatusCallback. TimeConvert time TimeConvert seconds, minute, hours, day, month, year, day_of_week, RFC The first form takes a HTTP date/time string and returns the date/time converted in the following array: *seconds, minute, hours, day, month, year, day_of_week*. The second form does the opposite (or at least it should, because actually seems to be malfunctioning): it takes the values and returns an HTTP date/time string, in the RFC format specified by the RFC parameter (OK, I didn't find yet any accepted value in the range 0..2000, let me know if you have more luck with it). Example: ($sec, $min, $hour, $day, $mday, $year, $wday) = $INET->TimeConvert("Sun, 26 Jan 1997 20:01:52 GMT"); # the opposite DOESN'T WORK! which value should $RFC have??? $time = $INET->TimeConvert(52, 1, 20, 26, 1, 1997, 0, $RFC); UserAgent [name] Reads or sets the user agent used for HTTP requests. If no name parameter is specified, the current value is returned; otherwise, the user agent is set to name. See also QueryOption and SetOption. Example: $INET->UserAgent("Mozilla/3.0"); $useragent = $INET->UserAgent(); Username [name] Reads or sets the username used for an FTP or HTTP connection. If no name parameter is specified, the current value is returned; otherwise, the username is set to name. See also Password, QueryOption and SetOption. Example: $HTTP->Username("dada"); $username = $HTTP->Username(); Version Returns the version numbers for the Win32::Internet package and the WININET.DLL version, as an array or string, depending on the context. The string returned will contain "package_version/DLL_version", while the array will contain: "package_version", "DLL_version". Example: $version = $INET->Version(); # should return "0.06/4.70.1215" @version = $INET->Version(); # should return ("0.06", "4.70.1215") FTP Functions ------------- *General Note* All methods assume that you have the following lines: use Win32::Internet; $INET = new Win32::Internet(); $INET->FTP($FTP, "hostname", "username", "password"); somewhere before the method calls; in other words, we assume that you have an Internet object called $INET and an open FTP session called $FTP. See new and FTP for more information. Methods Ascii Asc Sets the ASCII transfer mode for this FTP session. It will be applied to the subsequent Get functions. See also the Binary and Mode function. Example: $FTP->Ascii(); Binary Bin Sets the binary transfer mode for this FTP session. It will be applied to the subsequent Get functions. See also the Ascii and Mode function. Example: $FTP->Binary(); Cd path Cwd path Chdir path Changes the current directory on the FTP remote host. Returns path or undef on error. Example: $FTP->Cd("/pub"); Delete file Del file Deletes a file on the FTP remote host. Returns undef on error. Example: $FTP->Delete("110-i86.zip"); Get remote, [local, overwrite, flags, context] Gets the remote FTP file and saves it locally in local. If local is not specified, it will be the same name as remote. Returns undef on error. The parameters and their values are: * remote The name of the remote file on the FTP server. Default: none. * local The name of the local file to create. Default: remote. * overwrite If 0, overwrites local if it exists; with any other value, the function fails if the local file already exists. Default: 0. * flags Additional flags affecting the behavior of the function. Default: none. * context A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Default: none. Refer to the `"Microsoft Win32 Internet Functions"' in this node documentation for more details on those parameters. Example: $FTP->Get("110-i86.zip"); $FTP->Get("/pub/perl/languages/CPAN/00index.html", "CPAN_index.html"); List [pattern, listmode] Ls [pattern, listmode] Dir [pattern, listmode] Returns a list containing the files found in this directory, eventually matching the given pattern (which, if omitted, is considered "*.*"). The content of the returned list depends on the *listmode* parameter, which can have the following values: * listmode=1 (or omitted) the list contains the names of the files found. Example: @files = $FTP->List(); @textfiles = $FTP->List("*.txt"); foreach $file (@textfiles) { print "Name: ", $file, "\n"; } * listmode=2 the list contains 7 values for each file, which respectively are: * the file name * the DOS short file name, aka 8.3 * the size * the attributes * the creation time * the last access time * the last modified time Example: @files = $FTP->List("*.*", 2); for($i=0; $i<=$#files; $i+=7) { print "Name: ", @files[$i], "\n"; print "Size: ", @files[$i+2], "\n"; print "Attr: ", @files[$i+3], "\n"; } * listmode=3 the list contains a reference to an hash array for each found file; each hash contains: * name => the file name * altname => the DOS short file name, aka 8.3 * size => the size * attr => the attributes * ctime => the creation time * atime => the last access time * mtime => the last modified time Example: @files = $FTP->List("*.*", 3); foreach $file (@files) { print $file->{'name'}, " ", $file->{'size'}, " ", $file->{'attr'}, "\n"; } Note: all times are reported as strings of the following format: *second, hour, minute, day, month, year*. Example: $file->{'mtime'} == "0,10,58,9,12,1996" stands for 09 Dec 1996 at 10:58:00 Mkdir name Md name Creates a directory on the FTP remote host. Returns undef on error. Example: $FTP->Mkdir("NextBuild"); Mode [mode] If called with no arguments, returns the current transfer mode for this FTP session ("asc" for ASCII or "bin" for binary). The mode argument can be "asc" or "bin", in which case the appropriate transfer mode is selected. See also the Ascii and Binary functions. Returns undef on errors. Example: print "Current mode is: ", $FTP->Mode(); $FTP->Mode("asc"); # ... same as $FTP->Ascii(); Pasv [mode] If called with no arguments, returns 1 if the current FTP session has passive transfer mode enabled, 0 if not. You can call it with a mode parameter (0/1) only as a method of a Internet object (see new), in which case it will set the default value for the next FTP objects you create (read: set it before, because you can't change this value once you opened the FTP session). Example: print "Pasv is: ", $FTP->Pasv(); $INET->Pasv(1); $INET->FTP($FTP,"ftp.activeware.com", "anonymous", "dada\@divinf.it"); $FTP->Pasv(0); # this will be ignored... Put local, [remote, context] Upload the local file to the FTP server saving it under the name remote, which if if omitted is the same name as local. Returns undef on error. context is a number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Example: $FTP->Put("internet.zip"); $FTP->Put("d:/users/dada/temp.zip", "/temp/dada.zip"); Pwd Returns the current directory on the FTP server or undef on errors. Example: $path = $FTP->Pwd(); Rename oldfile, newfile Ren oldfile, newfile Renames a file on the FTP remote host. Returns undef on error. Example: $FTP->Rename("110-i86.zip", "68i-011.zip"); Rmdir name Rd name Removes a directory on the FTP remote host. Returns undef on error. Example: $FTP->Rmdir("CurrentBuild"); HTTP Functions -------------- *General Note* All methods assume that you have the following lines: use Win32::Internet; $INET = new Win32::Internet(); $INET->HTTP($HTTP, "hostname", "username", "password"); somewhere before the method calls; in other words, we assume that you have an Internet object called $INET and an open HTTP session called $HTTP. See new and HTTP for more information. Methods AddHeader header, [flags] Adds HTTP request headers to an HTTP request object created with OpenRequest. For the possible values of flags refer to the `"Microsoft Win32 Internet Functions"' in this node document. Example: $HTTP->OpenRequest($REQUEST,"/index.html"); $REQUEST->AddHeader("If-Modified-Since: Sunday, 17-Nov-96 11:40:03 GMT"); $REQUEST->AddHeader("Accept: text/html\r\n", HTTP_ADDREQ_FLAG_REPLACE); OpenRequest requestobject, [path, method, version, referer, accept, flags, context] OpenRequest requestobject, hashref Opens an HTTP request. Returns undef on errors or a number if the connection was succesful. You can then use one of the AddHeader, SendRequest, QueryInfo, QueryDataAvailable and ReadFile methods on the newly created *requestobject*. The parameters and their values are: * path The object to request. This is generally a file name, an executable module, etc. Default: / * method The method to use; can actually be GET, POST, HEAD or PUT. Default: GET * version The HTTP version. Default: HTTP/1.0 * referer The URL of the document from which the URL in the request was obtained. Default: none * accept The content types accepted. They must be separated by a "\0" (ASCII zero). Default: text/* image/gif image/jpeg * flags Additional flags affecting the behavior of the function. Default: none * context A number to identify this operation if it is asynchronous. See SetStatusCallback and GetStatusCallback for more info on asynchronous operations. Default: none Refer to the `"Microsoft Win32 Internet Functions"' in this node documentation for more details on those parameters. If you pass *hashref* (a reference to an hash array), the following values are taken from the array: %hash=( "path" => "path", "method" => "method", "version" => "version", "referer" => "referer", "accept" => "accept", "flags" => flags, "context" => context, ); See also Request. Example: $HTTP->OpenRequest($REQUEST, "/index.html"); $HTTP->OpenRequest($REQUEST, "/index.html", "GET", "HTTP/0.9"); $params{"path"} = "/index.html"; $params{"flags"} = " $HTTP->OpenRequest($REQUEST, \%params); QueryInfo header, [flags] Queries information about an HTTP request object created with OpenRequest. You can specify an header (for example, "Content-type") and/or one or more flags. If you don't specify flags, HTTP_QUERY_CUSTOM will be used by default; this means that header should contain a valid HTTP header name. For the possible values of flags refer to the `"Microsoft Win32 Internet Functions"' in this node document. Example: $HTTP->OpenRequest($REQUEST,"/index.html"); $statuscode = $REQUEST->QueryInfo("", HTTP_QUERY_STATUS_CODE); $headers = $REQUEST->QueryInfo("", HTTP_QUERY_RAW_HEADERS_CRLF); # will get all the headers $length = $REQUEST->QueryInfo("Content-length"); Request [path, method, version, referer, accept, flags] Request hashref Performs an HTTP request and returns an array containing the status code, the headers and the content of the file. It is a one-step procedure that makes an OpenRequest, a SendRequest, some QueryInfo, ReadFile and finally Close. For a description of the parameters, see OpenRequest. Example: ($statuscode, $headers, $file) = $HTTP->Request("/index.html"); ($s, $h, $f) = $HTTP->Request("/index.html", "GET", "HTTP/1.0"); SendRequest [postdata] Send an HTTP request to the destination server. *postdata* are any optional data to send immediately after the request header; this is generally used for POST or PUT requests. See also OpenRequest. Example: $HTTP->OpenRequest($REQUEST, "/index.html"); $REQUEST->SendRequest(); # A POST request... $HTTP->OpenRequest($REQUEST, "/cgi-bin/somescript.pl", "POST"); #This line is a must -> (thanks Philip :) $REQUEST->AddHeader("Content-Type: application/x-www-form-urlencoded"); $REQUEST->SendRequest("key1=value1&key2=value2&key3=value3"); APPENDIX ======== Microsoft Win32 Internet Functions ---------------------------------- Complete documentation for the Microsoft Win32 Internet Functions can be found, in both HTML and zipped Word format, at this address: http://www.microsoft.com/intdev/sdk/docs/wininet/ Functions Table --------------- This table reports the correspondence between the functions offered by WININET.DLL and their implementation in the Win32::Internet extension. Functions showing a "--" are not currently implemented. Functions enclosed in parens ( ) aren't implemented straightforwardly, but in a higher-level routine, eg. together with other functions. WININET.DLL Win32::Internet InternetOpen new Win32::Internet InternetConnect FTP / HTTP InternetCloseHandle Close InternetQueryOption QueryOption InternetSetOption SetOption InternetSetOptionEx --- InternetSetStatusCallback SetStatusCallback InternetStatusCallback GetStatusCallback InternetConfirmZoneCrossing --- InternetTimeFromSystemTime TimeConvert InternetTimeToSystemTime TimeConvert InternetAttemptConnect --- InternetReadFile ReadFile InternetSetFilePointer --- InternetFindNextFile (List) InternetQueryDataAvailable QueryDataAvailable InternetGetLastResponseInfo GetResponse InternetWriteFile --- InternetCrackUrl CrackURL InternetCreateUrl CreateURL InternetCanonicalizeUrl CanonicalizeURL InternetCombineUrl CombineURL InternetOpenUrl OpenURL FtpFindFirstFile (List) FtpGetFile Get FtpPutFile Put FtpDeleteFile Delete FtpRenameFile Rename FtpOpenFile --- FtpCreateDirectory Mkdir FtpRemoveDirectory Rmdir FtpSetCurrentDirectory Cd FtpGetCurrentDirectory Pwd HttpOpenRequest OpenRequest HttpAddRequestHeaders AddHeader HttpSendRequest SendRequest HttpQueryInfo QueryInfo InternetErrorDlg --- Actually, I don't plan to add support for Gopher, Cookie and Cache functions. I will if there will be consistent requests to do so. There are a number of higher-level functions in the Win32::Internet that simplify some usual procedures, calling more that one WININET API function. This table reports those functions and the relative WININET functions they use. Win32::Internet WININET.DLL FetchURL InternetOpenUrl InternetQueryDataAvailable InternetReadFile InternetCloseHandle ReadEntireFile InternetQueryDataAvailable InternetReadFile Request HttpOpenRequest HttpSendRequest HttpQueryInfo InternetQueryDataAvailable InternetReadFile InternetCloseHandle List FtpFindFirstFile InternetFindNextFile Constants --------- Those are the constants exported by the package in the main namespace (eg. you can use them in your scripts); for their meaning and proper use, refer to the Microsoft Win32 Internet Functions document. HTTP_ADDREQ_FLAG_ADD HTTP_ADDREQ_FLAG_REPLACE HTTP_QUERY_ALLOW HTTP_QUERY_CONTENT_DESCRIPTION HTTP_QUERY_CONTENT_ID HTTP_QUERY_CONTENT_LENGTH HTTP_QUERY_CONTENT_TRANSFER_ENCODING HTTP_QUERY_CONTENT_TYPE HTTP_QUERY_COST HTTP_QUERY_CUSTOM HTTP_QUERY_DATE HTTP_QUERY_DERIVED_FROM HTTP_QUERY_EXPIRES HTTP_QUERY_FLAG_REQUEST_HEADERS HTTP_QUERY_FLAG_SYSTEMTIME HTTP_QUERY_LANGUAGE HTTP_QUERY_LAST_MODIFIED HTTP_QUERY_MESSAGE_ID HTTP_QUERY_MIME_VERSION HTTP_QUERY_PRAGMA HTTP_QUERY_PUBLIC HTTP_QUERY_RAW_HEADERS HTTP_QUERY_RAW_HEADERS_CRLF HTTP_QUERY_REQUEST_METHOD HTTP_QUERY_SERVER HTTP_QUERY_STATUS_CODE HTTP_QUERY_STATUS_TEXT HTTP_QUERY_URI HTTP_QUERY_USER_AGENT HTTP_QUERY_VERSION HTTP_QUERY_WWW_LINK ICU_BROWSER_MODE ICU_DECODE ICU_ENCODE_SPACES_ONLY ICU_ESCAPE ICU_NO_ENCODE ICU_NO_META ICU_USERNAME INTERNET_CONNECT_FLAG_PASSIVE INTERNET_FLAG_ASYNC INTERNET_FLAG_HYPERLINK INTERNET_FLAG_KEEP_CONNECTION INTERNET_FLAG_MAKE_PERSISTENT INTERNET_FLAG_NO_AUTH INTERNET_FLAG_NO_AUTO_REDIRECT INTERNET_FLAG_NO_CACHE_WRITE INTERNET_FLAG_NO_COOKIES INTERNET_FLAG_READ_PREFETCH INTERNET_FLAG_RELOAD INTERNET_FLAG_RESYNCHRONIZE INTERNET_FLAG_TRANSFER_ASCII INTERNET_FLAG_TRANSFER_BINARY INTERNET_INVALID_PORT_NUMBER INTERNET_INVALID_STATUS_CALLBACK INTERNET_OPEN_TYPE_DIRECT INTERNET_OPEN_TYPE_PROXY INTERNET_OPEN_TYPE_PROXY_PRECONFIG INTERNET_OPTION_CONNECT_BACKOFF INTERNET_OPTION_CONNECT_RETRIES INTERNET_OPTION_CONNECT_TIMEOUT INTERNET_OPTION_CONTROL_SEND_TIMEOUT INTERNET_OPTION_CONTROL_RECEIVE_TIMEOUT INTERNET_OPTION_DATA_SEND_TIMEOUT INTERNET_OPTION_DATA_RECEIVE_TIMEOUT INTERNET_OPTION_HANDLE_TYPE INTERNET_OPTION_LISTEN_TIMEOUT INTERNET_OPTION_PASSWORD INTERNET_OPTION_READ_BUFFER_SIZE INTERNET_OPTION_USER_AGENT INTERNET_OPTION_USERNAME INTERNET_OPTION_VERSION INTERNET_OPTION_WRITE_BUFFER_SIZE INTERNET_SERVICE_FTP INTERNET_SERVICE_GOPHER INTERNET_SERVICE_HTTP INTERNET_STATUS_CLOSING_CONNECTION INTERNET_STATUS_CONNECTED_TO_SERVER INTERNET_STATUS_CONNECTING_TO_SERVER INTERNET_STATUS_CONNECTION_CLOSED INTERNET_STATUS_HANDLE_CLOSING INTERNET_STATUS_HANDLE_CREATED INTERNET_STATUS_NAME_RESOLVED INTERNET_STATUS_RECEIVING_RESPONSE INTERNET_STATUS_REDIRECT INTERNET_STATUS_REQUEST_COMPLETE INTERNET_STATUS_REQUEST_SENT INTERNET_STATUS_RESOLVING_NAME INTERNET_STATUS_RESPONSE_RECEIVED INTERNET_STATUS_SENDING_REQUEST VERSION HISTORY =============== * 0.081 (25 Sep 1999) * Documentation converted to pod format by Jan Dubois . * Minor changes from Perl 5.005xx compatibility. * 0.08 (14 Feb 1997) * fixed 2 more bugs in Option(s) related subs (thanks to Brian Helterline!). * Error() now gets error messages directly from WININET.DLL. * The PLL file now comes in 2 versions, one for Perl version 5.001 (build 100) and one for Perl version 5.003 (build 300 and higher). Everybody should be happy now :) * added an installation program. * 0.07 (10 Feb 1997) * fixed a bug in Version() introduced with 0.06... * completely reworked PM file, fixed *lots* of minor bugs, and removed almost all the warnings with "perl -w". * 0.06 (26 Jan 1997) * fixed another hideous bug in "new" (the 'class' parameter was still missing). * added support for asynchronous operations (work still in embryo). * removed the ending \0 (ASCII zero) from the DLL version returned by "Version". * added a lot of constants. * added safefree() after every safemalloc() in C... wonder why I didn't it before :) * added TimeConvert, which actually works one way only. * 0.05f (29 Nov 1996) * fixed a bug in "new" (parameters passed were simply ignored). * fixed another bug: "Chdir" and "Cwd" were aliases of RMDIR instead of CD.. * 0.05 (29 Nov 1996) * added "CrackURL" and "CreateURL". * corrected an error in TEST.PL (there was a GetUserAgent instead of UserAgent). * 0.04 (25 Nov 1996) * added "Version" to retrieve package and DLL versions. * added proxies and other options to "new". * changed "OpenRequest" and "Request" to read parameters from a hash. * added "SetOption/QueryOption" and a lot of relative functions (connect, username, password, useragent, etc.). * added "CanonicalizeURL" and "CombineURL". * "Error" covers a wider spectrum of errors. * 0.02 (18 Nov 1996) * added support for HTTP sessions and requests. * 0.01 (11 Nov 1996) * fetching of HTTP, FTP and GOPHER URLs. * complete set of commands to manage an FTP session. AUTHOR ====== Version 0.08 (14 Feb 1997) by Aldo Calpini CREDITS ======= Win32::Internet is based on the Win32::Registry code written by Jesse Dougherty. Additional thanks to: Carl Tichler for his help in the initial development; Tore Haraldsen, Brian Helterline for the bugfixes; Dave Roth for his great source code examples. DISCLAIMER ========== This program is FREE; you can redistribute, modify, disassemble, or even reverse engineer this software at your will. Keep in mind, however, that NOTHING IS GUARANTEED to work and everything you do is AT YOUR OWN RISK - I will not take responsability for any damage, loss of money and/or health that may arise from the use of this program! This is distributed under the terms of Larry Wall's Artistic License.