home *** CD-ROM | disk | FTP | other *** search
/ c't freeware shareware 1997 / CT_SW_97.ISO / pc / software / entwickl / win95 / pw32i306.exe / lib / Win32 / netresource.pm < prev    next >
Text File  |  1996-08-12  |  9KB  |  366 lines
  1. package Win32::NetResource;
  2.  
  3. require Exporter;
  4. require DynaLoader;
  5. require AutoLoader;
  6.  
  7. @ISA = qw(Exporter DynaLoader);
  8. # Items to export into callers namespace by default. Note: do not export
  9. # names by default without a very good reason. Use EXPORT_OK instead.
  10. # Do not simply export all your public functions/methods/constants.
  11. @EXPORT = qw(
  12.     RESOURCEDISPLAYTYPE_DOMAIN
  13.     RESOURCEDISPLAYTYPE_FILE
  14.     RESOURCEDISPLAYTYPE_GENERIC
  15.     RESOURCEDISPLAYTYPE_GROUP
  16.     RESOURCEDISPLAYTYPE_SERVER
  17.     RESOURCEDISPLAYTYPE_SHARE
  18.     RESOURCEDISPLAYTYPE_TREE
  19.     RESOURCETYPE_ANY
  20.     RESOURCETYPE_DISK
  21.     RESOURCETYPE_PRINT
  22.     RESOURCETYPE_UNKNOWN
  23.     RESOURCEUSAGE_CONNECTABLE
  24.     RESOURCEUSAGE_CONTAINER
  25.     RESOURCEUSAGE_RESERVED
  26.     RESOURCE_CONNECTED
  27.     RESOURCE_GLOBALNET
  28.     RESOURCE_REMEMBERED
  29. );
  30.  
  31. =head1 NAME
  32.  
  33. Win32::NetResource - manage network resources in perl
  34.  
  35. =head1 SYNOPSIS
  36.  
  37.     use Win32::NetResource;
  38.  
  39.     $ShareInfo = {
  40.                     'path' => "C:\\MyShareDir",
  41.                     'netname' => "MyShare",
  42.                     'remark' => "It is good to share",
  43.                     'passwd' => "",
  44.                     'current-users' =>0,
  45.                     'permissions' => 0,
  46.                     'maxusers' => -1,
  47.                     'type'  => 0,
  48.                     };
  49.     
  50.    Win32::NetResource::NetShareAdd( $ShareInfo,$parm )|| die "unable to add share\n";
  51.  
  52.  
  53. =head1 DESCRIPTION
  54.  
  55. This module offers control over the network resources of Win32.Disks,
  56. printers etc can be shared over a network.
  57.  
  58. =head1 DATA TYPES
  59. There are two main data types required to control network resources.
  60. In Perl these are represented by hash types.
  61.  
  62. =over 10
  63. =item %NETRESOURCE
  64.  
  65.         KEY                VALUE
  66.         'Scope'            =>    Scope of an Enumeration
  67.                             RESOURCE_CONNECTED,
  68.                             RESOURCE_GLOBALNET,
  69.                             RESOURCE_REMEMBERED.
  70.  
  71.         'Type'            =>    The type of resource to Enum
  72.                             RESOURCETYPE_ANY    All resources
  73.                             RESOURCETYPE_DISK    Disk resources
  74.                             RESOURCETYPE_PRINT    Print resources
  75.  
  76.         'DisplayType'    =>    The way the resource should be displayed.
  77.                             RESOURCEDISPLAYTYPE_DOMAIN    
  78.                             The object should be displayed as a domain.
  79.                             RESOURCEDISPLAYTYPE_GENERIC    
  80.                             The method used to display the object does not matter.
  81.                             RESOURCEDISPLAYTYPE_SERVER    
  82.                             The object should be displayed as a server.
  83.                             RESOURCEDISPLAYTYPE_SHARE    
  84.                             The object should be displayed as a sharepoint.
  85.  
  86.         'Usage'         =>        Specifies the Resources usage:
  87.                                 RESOURCEUSAGE_CONNECTABLE
  88.                                 RESOURCEUSAGE_CONTAINER.
  89.  
  90.         'LocalName'        =>        Name of the local device the resource is 
  91.                                 connected to.
  92.  
  93.         'RemoteName'    =>        The network name of the resource.
  94.         'Comment'        =>        A string comment.
  95.         'Provider'        =>        Name of the provider of the resource.
  96.  
  97. =back    
  98. =item %SHARE_INFO
  99.  
  100. This hash represents the SHARE_INFO_502 struct.
  101. =over 10
  102.         KEY                    VALUE
  103.         'netname'        =>    Name of the share.
  104.         'type'            =>    type of share.
  105.         'remark'        =>    A string comment.
  106.         'permissions'    =>    Permissions value
  107.         'maxusers'         =>    the max # of users.
  108.         'current-users'    =>    the current # of users.
  109.         'path'            =>    The path of the share.
  110.         'passwd'        =>    A password if one is req'd
  111.  
  112. =back
  113. =head1 FUNCTIONS
  114.  
  115. =head2 NOTE:
  116. all of the functions return FALSE (0) if they fail.
  117.  
  118. =over 10
  119.  
  120. =item GetSharedResources(\@Resources,dwType)
  121.     Creates a list in @Resources of %NETRESOURCE hash references.
  122.  
  123. =item AddConnection(\%NETRESOURCE,$Password,$UserName,$Connection)
  124.     Makes a connection to a network resource specified by %NETRESOURCE
  125.  
  126. =item CancelConnection($Name,$Connection,$Force)
  127.     Cancels a connection to a network resource connected to local device 
  128.     $name.$Connection is either 1 - persistent connection or 0, non-persistent.
  129.  
  130. =item WNetGetLastError($ErrorCode,$Description,$Name)
  131.     Gets the Extended Network Error.
  132.  
  133. =item GetError( $ErrorCode )
  134.     Gets the last Error for a Win32::NetResource call.
  135.  
  136. =item GetUNCName( $UNCName, $LocalPath );
  137.     returns the UNC name of the disk share connected to $LocalPath in $UNCName.
  138.  
  139. =head2 servername is optional for all the calls below. ( if not given the local machine is assumed. )
  140.  
  141. =item NetShareAdd(\%SHARE,$parm_err,$servername = NULL )
  142.     Add a share for sharing.
  143.  
  144. =item NetShareCheck($device,$type,$servername = NULL )
  145.     Check if a share is available for connection.
  146.  
  147. =item NetShareDel( $netname, $servername = NULL )
  148.     Remove a share from a machines list of shares.
  149.  
  150. =item NetShareGetInfo( $netname, \%SHARE,$servername=NULL )
  151.     Get the %SHARE_INFO information about the share $netname on the server $servername.
  152.  
  153. =item NetShareSetInfo( $netname,\%SHARE,$parm_err,$servername=NULL)
  154.     Set the information for share $netname.
  155.  
  156. =back
  157.  
  158. =cut
  159.  
  160. sub AUTOLOAD {
  161.     # This AUTOLOAD is used to 'autoload' constants from the constant()
  162.     # XS function.  If a constant is not found then control is passed
  163.     # to the AUTOLOAD in AutoLoader.
  164.  
  165.     my($constname);
  166.     ($constname = $AUTOLOAD) =~ s/.*:://;
  167.     #reset $! to zero to reset any current errors.
  168.     $!=0;
  169.     my $val = constant($constname, @_ ? $_[0] : 0);
  170.     if ($! != 0) {
  171.     if ($! =~ /Invalid/) {
  172.         $AutoLoader::AUTOLOAD = $AUTOLOAD;
  173.         goto &AutoLoader::AUTOLOAD;
  174.     }
  175.     else {
  176.         ($pack,$file,$line) = caller;
  177.         die "Your vendor has not defined Win32::NetResource macro $constname, used at $file line $line.
  178. ";
  179.     }
  180.     }
  181.     eval "sub $AUTOLOAD { $val }";
  182.     goto &$AUTOLOAD;
  183. }
  184.  
  185. sub AddConnection
  186. {
  187.     local $NetResource = _hash2NET( $_[0] );
  188.  
  189.     _AddConnection($NetResource,$_[1],$_[2],$_[3]);
  190. }
  191.  
  192.  
  193.  
  194. sub GetSharedResources
  195. {
  196.     ( ref $_[0] == ARRAY )||
  197.         die "GetSharedResources: ARRAY reference required\n";
  198.  
  199.     local $Aref = [];
  200.     local $Href;
  201.     local $Ret;
  202.  
  203.     # Get the shared resources.
  204.  
  205.     $Ret = _GetSharedResources( $Aref ,$_[1] );
  206.     
  207.     #build the array of hashes in $_[0]
  208.     
  209.     foreach ( @$Aref ){
  210.         $Href = _NET2hash( $_ );
  211.         push( @{$_[0]}, $Href );
  212.     }
  213.  
  214.     $Ret;
  215. }
  216.  
  217. sub NetShareAdd
  218. {
  219.     local $ShareInfo;
  220.     $ShareInfo = _hash2SHARE( $_[0] );
  221.     _NetShareAdd($ShareInfo,$_[1],$_[2]);
  222.  
  223. }
  224.  
  225. sub NetShareGetInfo
  226. {
  227.     local $NetInfo,$Val;
  228.     $Val = _NetShareGetInfo( $_[0],$NetInfo,$_[2]);
  229.  
  230.     $_[1] = _SHARE2hash( $NetInfo );    
  231.  
  232.     $Val;
  233. }
  234.  
  235. sub NetShareSetInfo
  236. {
  237.     local $ShareInfo;
  238.     $ShareInfo = _hash2SHARE( $_[3] );
  239.  
  240.     _NetShareSetInfo( $_[0],$_[1],$_[2],$ShareInfo,$_[4]);
  241.  
  242. }
  243.  
  244.  
  245. #These are private functions to work with the ShareInfo structure.
  246. #please note that the implementation of these calls requires the SHARE_INFO_502 level
  247. #of information.
  248.  
  249. sub _SHARE2hash
  250. {
  251.     my $ShareRef = $_[0];
  252.  
  253.     local $netname,$type,$remark,$permissions,$maxusers;
  254.     local $current_users,$path,$passwd;
  255.     
  256.     ($type,$permissions,$maxuses,$current_users,$remark,$netname,$path,$passwd)=
  257.         unpack('i4 A257 A81 A257 A257',$ShareRef);
  258.  
  259.     $Hash={     'netname'        =>    $netname,
  260.                 'type'            =>    $type,
  261.                 'remark'        =>    $remark,
  262.                 'permissions'    =>    $permissions,
  263.                 'maxusers'         =>    $maxuses,
  264.                 'current-users'    =>    $current_users,
  265.                 'path'            =>    $path,
  266.                 'passwd'        =>    $passwd,
  267.             };
  268.  
  269.     $Hash;
  270.  
  271.  
  272. }
  273.  
  274. sub _hash2SHARE
  275. {
  276.     local $Hash = $_[0];
  277.        local $ShareRef;
  278.  
  279.     ( ref $Hash == HASH )||
  280.         die "reference passed is not a hash reference\n";
  281.  
  282.  
  283.     local $netname,$type,$remark,$permissions,$maxusers;
  284.     local $current_users,$path,$passwd;
  285.  
  286.     $netname = $Hash->{'netname'} . "\0";
  287.     $type        =    $Hash->{'type'} . "\0";
  288.     $remark        =    $Hash->{'remark'} . "\0";
  289.     $permissions=    $Hash->{'permissions'} . "\0";
  290.     $maxusers    =    $Hash->{'maxusers'} . "\0";
  291.     $current_users= $Hash->{'current_users'} . "\0";
  292.     $path        =    $Hash->{'path'} . "\0";
  293.     $passwd        =    $Hash->{'passwd'} . "\0";
  294.  
  295.     $ShareRef = pack( 'i4 A257 A81 A257 A257',$type,$permissions,$maxusers,$current_users,$remark,$netname,$path,$passwd);
  296.     
  297.     $ShareRef; 
  298. }
  299.  
  300. #These are private functions to translate the NETRESOURCE structure to a hash
  301. # for manipulation in perl.
  302. #typedef struct _NETRESOURCE {  // nr  
  303. #    DWORD  dwScope; 
  304. #    DWORD  dwType; 
  305. #    DWORD  dwDisplayType; 
  306. #    DWORD  dwUsage; 
  307. #    LPTSTR lpLocalName; 
  308. #    LPTSTR lpRemoteName; 
  309. #    LPTSTR lpComment; 
  310. #    LPTSTR lpProvider; 
  311. #} NETRESOURCE; 
  312.  
  313.  sub _NET2hash
  314. {
  315.     my $netref = $_[0];
  316.      local $Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider;
  317.  
  318.     ($Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider) =
  319.         unpack( "i4 p4", $netref );
  320.  
  321.  
  322. $Hash = {
  323.         'Scope'        =>        $Scope,
  324.         'Type'        =>        $Type,
  325.         'DisplayType'    =>    $DisplayType,
  326.         'Usage'     =>        $Usage,
  327.         'LocalName'    =>        $LocalName,
  328.         'RemoteName'    =>    $RemoteName,
  329.         'Comment'    =>        $Comment,
  330.         'Provider'    =>        $Provider,
  331.         };
  332.  
  333.     $Hash;
  334. }
  335.  
  336. sub _hash2NET
  337. {
  338.     my $hashref = $_[0];
  339.     ( ref $hashref == HASH )|| die "Hash reference required\n";
  340.      local $Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider;
  341.  
  342.     $Scope         =        $hashref->{'Scope'};
  343.     $Type         =         $hashref->{'Type'};
  344.     $DisplayType =        $hashref->{'DisplayType'};
  345.     $Usage         =         $hashref->{'Usage'};
  346.     $LocalName     =        $hashref->{'LocalName'};
  347.     $RemoteName =        $hashref->{'RemoteName'};
  348.     $Comment     =        $hashref->{'Comment'};
  349.     $Provider    =        $hashref->{'Provider'};
  350.  
  351.     $hashref = pack( 'i4 p4',$Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider);
  352.  
  353.     $hashref;
  354.  
  355. }
  356.  
  357.  
  358. bootstrap Win32::NetResource;
  359.  
  360. # Preloaded methods go here.
  361.  
  362. # Autoload methods go after __END__, and are processed by the autosplit program.
  363.  
  364. 1;
  365. __END__
  366.