home *** CD-ROM | disk | FTP | other *** search
/ PC World 2005 June / PCWorld_2005-06_cd.bin / software / vyzkuste / firewally / firewally.exe / framework-2.3.exe / NetResource.pm < prev    next >
Text File  |  2002-07-08  |  12KB  |  457 lines
  1. package Win32::NetResource;
  2.  
  3. require Exporter;
  4. require DynaLoader;
  5. require AutoLoader;
  6.  
  7. $VERSION = '0.053';
  8.  
  9. @ISA = qw(Exporter DynaLoader);
  10. # Items to export into callers namespace by default. Note: do not export
  11. # names by default without a very good reason. Use EXPORT_OK instead.
  12. # Do not simply export all your public functions/methods/constants.
  13. @EXPORT = qw(
  14.     RESOURCEDISPLAYTYPE_DOMAIN
  15.     RESOURCEDISPLAYTYPE_FILE
  16.     RESOURCEDISPLAYTYPE_GENERIC
  17.     RESOURCEDISPLAYTYPE_GROUP
  18.     RESOURCEDISPLAYTYPE_SERVER
  19.     RESOURCEDISPLAYTYPE_SHARE
  20.     RESOURCEDISPLAYTYPE_TREE
  21.     RESOURCETYPE_ANY
  22.     RESOURCETYPE_DISK
  23.     RESOURCETYPE_PRINT
  24.     RESOURCETYPE_UNKNOWN
  25.     RESOURCEUSAGE_CONNECTABLE
  26.     RESOURCEUSAGE_CONTAINER
  27.     RESOURCEUSAGE_RESERVED
  28.     RESOURCE_CONNECTED
  29.     RESOURCE_GLOBALNET
  30.     RESOURCE_REMEMBERED
  31.     STYPE_DISKTREE
  32.     STYPE_PRINTQ
  33.     STYPE_DEVICE
  34.     STYPE_IPC
  35.     STYPE_SPECIAL
  36.     SHARE_NETNAME_PARMNUM
  37.     SHARE_TYPE_PARMNUM
  38.     SHARE_REMARK_PARMNUM
  39.     SHARE_PERMISSIONS_PARMNUM
  40.     SHARE_MAX_USES_PARMNUM
  41.     SHARE_CURRENT_USES_PARMNUM
  42.     SHARE_PATH_PARMNUM
  43.     SHARE_PASSWD_PARMNUM
  44.     SHARE_FILE_SD_PARMNUM
  45. );
  46.  
  47. @EXPORT_OK = qw(
  48.     GetSharedResources
  49.     AddConnection
  50.     CancelConnection
  51.     WNetGetLastError
  52.     GetError
  53.     GetUNCName
  54.     NetShareAdd
  55.     NetShareCheck
  56.     NetShareDel
  57.     NetShareGetInfo
  58.     NetShareSetInfo
  59. );
  60.  
  61. =head1 NAME
  62.  
  63. Win32::NetResource - manage network resources in perl
  64.  
  65. =head1 SYNOPSIS
  66.  
  67.     use Win32::NetResource;
  68.  
  69.     $ShareInfo = {
  70.                     'path' => "C:\\MyShareDir",
  71.                     'netname' => "MyShare",
  72.                     'remark' => "It is good to share",
  73.                     'passwd' => "",
  74.                     'current-users' =>0,
  75.                     'permissions' => 0,
  76.                     'maxusers' => -1,
  77.                     'type'  => 0,
  78.                     };
  79.     
  80.     Win32::NetResource::NetShareAdd( $ShareInfo,$parm )
  81.         or die "unable to add share";
  82.  
  83.  
  84. =head1 DESCRIPTION
  85.  
  86. This module offers control over the network resources of Win32.Disks,
  87. printers etc can be shared over a network.
  88.  
  89. =head1 DATA TYPES
  90.  
  91. There are two main data types required to control network resources.
  92. In Perl these are represented by hash types.
  93.  
  94. =over 4
  95.  
  96. =item %NETRESOURCE
  97.  
  98.     KEY                    VALUE
  99.     
  100.     'Scope'         =>  Scope of an Enumeration
  101.             RESOURCE_CONNECTED,
  102.             RESOURCE_GLOBALNET,
  103.             RESOURCE_REMEMBERED.
  104.     
  105.     'Type'          =>  The type of resource to Enum
  106.             RESOURCETYPE_ANY    All resources
  107.             RESOURCETYPE_DISK    Disk resources
  108.             RESOURCETYPE_PRINT    Print resources
  109.     
  110.     'DisplayType'   =>  The way the resource should be displayed.
  111.             RESOURCEDISPLAYTYPE_DOMAIN    
  112.             The object should be displayed as a domain.
  113.             RESOURCEDISPLAYTYPE_GENERIC    
  114.             The method used to display the object does not matter.
  115.             RESOURCEDISPLAYTYPE_SERVER    
  116.             The object should be displayed as a server.
  117.             RESOURCEDISPLAYTYPE_SHARE    
  118.             The object should be displayed as a sharepoint.
  119.     
  120.     'Usage'         =>  Specifies the Resources usage:
  121.             RESOURCEUSAGE_CONNECTABLE
  122.             RESOURCEUSAGE_CONTAINER.
  123.     
  124.     'LocalName'     =>  Name of the local device the resource is 
  125.             connected to.
  126.     
  127.     'RemoteName'    =>  The network name of the resource.
  128.     
  129.     'Comment'       =>  A string comment.
  130.     
  131.     'Provider'      =>  Name of the provider of the resource.
  132.  
  133. =back    
  134.  
  135. =item %SHARE_INFO
  136.  
  137. This hash represents the SHARE_INFO_502 struct.
  138.  
  139. =over 4
  140.  
  141.     KEY                    VALUE
  142.     'netname'        =>    Name of the share.
  143.     'type'           =>    type of share.
  144.     'remark'         =>    A string comment.
  145.     'permissions'    =>    Permissions value
  146.     'maxusers'       =>    the max # of users.
  147.     'current-users'  =>    the current # of users.
  148.     'path'           =>    The path of the share.
  149.     'passwd'         =>    A password if one is req'd
  150.  
  151. =back
  152.  
  153. =head1 FUNCTIONS
  154.  
  155. =head2 NOTE
  156.  
  157. All of the functions return false if they fail.
  158.  
  159. =over 4
  160.  
  161. =item GetSharedResources(\@Resources,dwType,\%NetResource = NULL)
  162.  
  163. Creates a list in @Resources of %NETRESOURCE hash references.
  164.  
  165. The return value indicates whether there was an error in accessing
  166. any of the shared resources.  All the shared resources that were
  167. encountered (until the point of an error, if any) are pushed into
  168. @Resources as references to %NETRESOURCE hashes.  See example
  169. below.  The \%NetResource argument is optional.  If it is not supplied,
  170. the root (that is, the topmost container) of the network is assumed,
  171. and all network resources available from the toplevel container will
  172. be enumerated.
  173.  
  174. =item AddConnection(\%NETRESOURCE,$Password,$UserName,$Connection)
  175.  
  176. Makes a connection to a network resource specified by %NETRESOURCE
  177.  
  178. =item CancelConnection($Name,$Connection,$Force)
  179.  
  180. Cancels a connection to a network resource connected to local device 
  181. $name.$Connection is either 1 - persistent connection or 0, non-persistent.
  182.  
  183. =item WNetGetLastError($ErrorCode,$Description,$Name)
  184.  
  185. Gets the Extended Network Error.
  186.  
  187. =item GetError( $ErrorCode )
  188.  
  189. Gets the last Error for a Win32::NetResource call.
  190.  
  191. =item GetUNCName( $UNCName, $LocalPath );
  192.  
  193. Returns the UNC name of the disk share connected to $LocalPath in $UNCName.
  194. $LocalPath should be a drive based path. e.g. "C:\\share\\subdir"
  195.  
  196. =back
  197.  
  198. =head2 NOTE
  199.  
  200. $servername is optional for all the calls below. (if not given the
  201. local machine is assumed.)
  202.  
  203. =over 4
  204.  
  205. =item NetShareAdd(\%SHARE,$parm_err,$servername = NULL )
  206.  
  207. Add a share for sharing.
  208.  
  209. =item NetShareCheck($device,$type,$servername = NULL )
  210.  
  211. Check if a directory or a device is available for connection from the
  212. network through a share.  This includes all directories that are
  213. reachable through a shared directory or device, meaning that if C:\foo
  214. is shared, C:\foo\bar is also available for sharing.  This means that
  215. this function is pretty useless, given that by default every disk
  216. volume has an administrative share such as "C$" associated with its
  217. root directory.
  218.  
  219. $device must be a drive name, directory, or a device.  For example,
  220. "C:", "C:\dir", "LPT1", "D$", "IPC$" are all valid as the $device
  221. argument.  $type is an output argument that will be set to one of
  222. the following constants that describe the type of share:
  223.  
  224.     STYPE_DISKTREE     Disk drive 
  225.     STYPE_PRINTQ       Print queue 
  226.     STYPE_DEVICE       Communication device 
  227.     STYPE_IPC          Interprocess communication (IPC) 
  228.     STYPE_SPECIAL      Special share reserved for interprocess
  229.                          communication (IPC$) or remote administration
  230.                          of the server (ADMIN$). Can also refer to
  231.                          administrative shares such as C$, D$, etc.
  232.  
  233. =item NetShareDel( $netname, $servername = NULL )
  234.  
  235. Remove a share from a machines list of shares.
  236.  
  237. =item NetShareGetInfo( $netname, \%SHARE,$servername=NULL )
  238.  
  239. Get the %SHARE_INFO information about the share $netname on the
  240. server $servername.
  241.  
  242. =item NetShareSetInfo( $netname,\%SHARE,$parm_err,$servername=NULL)
  243.  
  244. Set the information for share $netname.
  245.  
  246. =back
  247.  
  248. =head1 EXAMPLE
  249.  
  250. =over 4
  251.  
  252. =item Enumerating all resources on the network
  253.  
  254.     #
  255.     # This example displays all the share points in the entire
  256.     # visible part of the network.
  257.     #
  258.  
  259.     use strict;
  260.     use Win32::NetResource qw(:DEFAULT GetSharedResources GetError);
  261.     my $resources = [];
  262.     unless(GetSharedResources($resources, RESOURCETYPE_ANY)) {
  263.     my $err;
  264.     GetError($err);
  265.     warn Win32::FormatMessage($err);
  266.     }
  267.  
  268.     foreach my $href (@$resources) {
  269.     next if ($$href{DisplayType} != RESOURCEDISPLAYTYPE_SHARE);
  270.     print "-----\n";
  271.     foreach( keys %$href){
  272.         print "$_: $href->{$_}\n";
  273.     }
  274.     }
  275.  
  276. =item Enumerating all resources on a particular host
  277.  
  278.     #
  279.     # This example displays all the share points exported by the local
  280.     # host.
  281.     #
  282.  
  283.     use strict;
  284.     use Win32::NetResource qw(:DEFAULT GetSharedResources GetError);
  285.     if (GetSharedResources(my $resources, RESOURCETYPE_ANY,
  286.                { RemoteName => "\\\\" . Win32::NodeName() }))
  287.     {
  288.     foreach my $href (@$resources) {
  289.         print "-----\n";
  290.         foreach(keys %$href) { print "$_: $href->{$_}\n"; }
  291.     }
  292.     }
  293.  
  294. =back
  295.  
  296. =head1 AUTHOR
  297.  
  298. Jesse Dougherty for Hip Communications.
  299.  
  300. Additional general cleanups and bug fixes by Gurusamy Sarathy <gsar@activestate.com>.
  301.  
  302. =cut
  303.  
  304. sub AUTOLOAD {
  305.     # This AUTOLOAD is used to 'autoload' constants from the constant()
  306.     # XS function.  If a constant is not found then control is passed
  307.     # to the AUTOLOAD in AutoLoader.
  308.  
  309.     my($constname);
  310.     ($constname = $AUTOLOAD) =~ s/.*:://;
  311.     #reset $! to zero to reset any current errors.
  312.     local $! = 0;
  313.     my $val = constant($constname, @_ ? $_[0] : 0);
  314.     if ($! != 0) {
  315.         if ($! =~ /Invalid/) {
  316.             $AutoLoader::AUTOLOAD = $AUTOLOAD;
  317.             goto &AutoLoader::AUTOLOAD;
  318.         }
  319.         else {
  320.             ($pack,$file,$line) = caller;
  321.             die "Your vendor has not defined Win32::NetResource macro $constname, used at $file line $line.
  322. ";
  323.         }
  324.     }
  325.     eval "sub $AUTOLOAD { $val }";
  326.     goto &$AUTOLOAD;
  327. }
  328.  
  329. sub AddConnection
  330. {
  331.     my $h = $_[0];
  332.     die "AddConnection: HASH reference required" unless ref($h) eq "HASH";
  333.  
  334.     #
  335.     # The last four items *must* not be deallocated until the
  336.     # _AddConnection() completes (since the packed structure is
  337.     # pointing into these values.
  338.     #
  339.     my $netres = pack( 'i4 p4', $h->{Scope},
  340.                     $h->{Type},
  341.                 $h->{DisplayType},
  342.                 $h->{Usage},
  343.                 $h->{LocalName},
  344.                 $h->{RemoteName},
  345.                 $h->{Comment},
  346.                 $h->{Provider});
  347.     _AddConnection($netres,$_[1],$_[2],$_[3]);
  348. }
  349.  
  350. #use Data::Dumper;
  351.  
  352. sub GetSharedResources
  353. {
  354.     die "GetSharedResources: ARRAY reference required"
  355.     if defined $_[0] and ref($_[0]) ne "ARRAY";
  356.  
  357.     my $aref = [];
  358.  
  359.     # Get the shared resources.
  360.  
  361.     my $ret;
  362.  
  363.     if (@_ > 2 and $_[2]) {
  364.     my $netres = pack('i4 p4', @{$_[2]}{qw(Scope
  365.                            Type
  366.                            DisplayType
  367.                            Usage
  368.                            LocalName
  369.                            RemoteName
  370.                            Comment
  371.                            Provider)});
  372.     $ret = _GetSharedResources( $aref , $_[1], $netres );
  373.     }
  374.     else {
  375.     $ret = _GetSharedResources( $aref , $_[1] );
  376.     }
  377.     
  378.     # build the array of hashes in $_[0]
  379. #   print Dumper($aref);    
  380.     foreach ( @$aref ) {
  381.     my %hash;
  382.     @hash{'Scope',
  383.           'Type',
  384.           'DisplayType',
  385.           'Usage',
  386.           'LocalName',
  387.           'RemoteName',
  388.           'Comment',
  389.           'Provider'} = split /\001/, $_;
  390.     push @{$_[0]}, \%hash;
  391.     }
  392.  
  393.     $ret;
  394. }
  395.  
  396. sub NetShareAdd
  397. {
  398.     my $shareinfo = _hash2SHARE( $_[0] );
  399.     _NetShareAdd($shareinfo,$_[1], $_[2] || "");
  400. }
  401.  
  402. sub NetShareGetInfo
  403. {
  404.     my ($netinfo,$val);
  405.     $val = _NetShareGetInfo( $_[0],$netinfo,$_[2] || "");
  406.     %{$_[1]} = %{_SHARE2hash( $netinfo )};    
  407.     $val;
  408. }
  409.  
  410. sub NetShareSetInfo
  411. {
  412.     my $shareinfo = _hash2SHARE( $_[1] );
  413.     _NetShareSetInfo( $_[0],$shareinfo,$_[2],$_[3] || "");
  414. }
  415.  
  416.  
  417. # These are private functions to work with the ShareInfo structure.
  418. # please note that the implementation of these calls requires the
  419. # SHARE_INFO_502 level of information.
  420.  
  421. sub _SHARE2hash
  422. {
  423.     my %hash = ();
  424.     @hash{'type',
  425.           'permissions',
  426.           'maxusers',
  427.           'current-users',
  428.           'remark',
  429.           'netname',
  430.           'path',
  431.           'passwd'} = unpack('i4 A257 A81 A257 A257',$_[0]);
  432.  
  433.     return \%hash;
  434. }
  435.  
  436. sub _hash2SHARE
  437. {
  438.     my $h = $_[0];
  439.     die "Argument must be a HASH reference" unless ref($h) eq "HASH";
  440.  
  441.     return pack 'i4 a257 a81 a257 a257',
  442.          @$h{'type',
  443.             'permissions',
  444.             'maxusers',
  445.             'current-users',
  446.             'remark',
  447.             'netname',
  448.             'path',
  449.             'passwd'};
  450. }
  451.  
  452.  
  453. bootstrap Win32::NetResource;
  454.  
  455. 1;
  456. __END__
  457.