home *** CD-ROM | disk | FTP | other *** search
/ Total Network Tools 2002 / NextStepPublishing-TotalNetworkTools2002-Win95.iso / Archive / Web Server / Savant.exe / disk1 / data1.cab / Perl5 / perl5 / lib / Win32 / netresource.pm < prev    next >
Encoding:
Perl POD Document  |  2001-02-23  |  9.2 KB  |  368 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.     if ($Ret != 0) {
  210.         foreach ( @$Aref ){
  211.             $Href = _NET2hash( $_ );
  212.             push( @{$_[0]}, $Href );
  213.         }
  214.     }
  215.  
  216.     $Ret;
  217. }
  218.  
  219. sub NetShareAdd
  220. {
  221.     local $ShareInfo;
  222.     $ShareInfo = _hash2SHARE( $_[0] );
  223.     _NetShareAdd($ShareInfo,$_[1],$_[2]);
  224.  
  225. }
  226.  
  227. sub NetShareGetInfo
  228. {
  229.     local $NetInfo,$Val;
  230.     $Val = _NetShareGetInfo( $_[0],$NetInfo,$_[2]);
  231.  
  232.     $_[1] = _SHARE2hash( $NetInfo );    
  233.  
  234.     $Val;
  235. }
  236.  
  237. sub NetShareSetInfo
  238. {
  239.     local $ShareInfo;
  240.     $ShareInfo = _hash2SHARE( $_[3] );
  241.  
  242.     _NetShareSetInfo( $_[0],$_[1],$_[2],$ShareInfo,$_[4]);
  243.  
  244. }
  245.  
  246.  
  247. #These are private functions to work with the ShareInfo structure.
  248. #please note that the implementation of these calls requires the SHARE_INFO_502 level
  249. #of information.
  250.  
  251. sub _SHARE2hash
  252. {
  253.     my $ShareRef = $_[0];
  254.  
  255.     local $netname,$type,$remark,$permissions,$maxusers;
  256.     local $current_users,$path,$passwd;
  257.     
  258.     ($type,$permissions,$maxuses,$current_users,$remark,$netname,$path,$passwd)=
  259.         unpack('i4 A257 A81 A257 A257',$ShareRef);
  260.  
  261.     $Hash={     'netname'        =>    $netname,
  262.                 'type'            =>    $type,
  263.                 'remark'        =>    $remark,
  264.                 'permissions'    =>    $permissions,
  265.                 'maxusers'         =>    $maxuses,
  266.                 'current-users'    =>    $current_users,
  267.                 'path'            =>    $path,
  268.                 'passwd'        =>    $passwd,
  269.             };
  270.  
  271.     $Hash;
  272.  
  273.  
  274. }
  275.  
  276. sub _hash2SHARE
  277. {
  278.     local $Hash = $_[0];
  279.        local $ShareRef;
  280.  
  281.     ( ref $Hash == HASH )||
  282.         die "reference passed is not a hash reference\n";
  283.  
  284.  
  285.     local $netname,$type,$remark,$permissions,$maxusers;
  286.     local $current_users,$path,$passwd;
  287.  
  288.     $netname = $Hash->{'netname'} . "\0";
  289.     $type        =    $Hash->{'type'} . "\0";
  290.     $remark        =    $Hash->{'remark'} . "\0";
  291.     $permissions=    $Hash->{'permissions'} . "\0";
  292.     $maxusers    =    $Hash->{'maxusers'} . "\0";
  293.     $current_users= $Hash->{'current_users'} . "\0";
  294.     $path        =    $Hash->{'path'} . "\0";
  295.     $passwd        =    $Hash->{'passwd'} . "\0";
  296.  
  297.     $ShareRef = pack( 'i4 A257 A81 A257 A257',$type,$permissions,$maxusers,$current_users,$remark,$netname,$path,$passwd);
  298.     
  299.     $ShareRef; 
  300. }
  301.  
  302. #These are private functions to translate the NETRESOURCE structure to a hash
  303. # for manipulation in perl.
  304. #typedef struct _NETRESOURCE {  // nr  
  305. #    DWORD  dwScope; 
  306. #    DWORD  dwType; 
  307. #    DWORD  dwDisplayType; 
  308. #    DWORD  dwUsage; 
  309. #    LPTSTR lpLocalName; 
  310. #    LPTSTR lpRemoteName; 
  311. #    LPTSTR lpComment; 
  312. #    LPTSTR lpProvider; 
  313. #} NETRESOURCE; 
  314.  
  315.  sub _NET2hash
  316. {
  317.     my $netref = $_[0];
  318.      local $Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider;
  319.  
  320.     ($Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider) =
  321.         unpack( "i4 p4", $netref );
  322.  
  323.  
  324. $Hash = {
  325.         'Scope'        =>        $Scope,
  326.         'Type'        =>        $Type,
  327.         'DisplayType'    =>    $DisplayType,
  328.         'Usage'     =>        $Usage,
  329.         'LocalName'    =>        $LocalName,
  330.         'RemoteName'    =>    $RemoteName,
  331.         'Comment'    =>        $Comment,
  332.         'Provider'    =>        $Provider,
  333.         };
  334.  
  335.     $Hash;
  336. }
  337.  
  338. sub _hash2NET
  339. {
  340.     my $hashref = $_[0];
  341.     ( ref $hashref == HASH )|| die "Hash reference required\n";
  342.      local $Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider;
  343.  
  344.     $Scope         =        $hashref->{'Scope'};
  345.     $Type         =         $hashref->{'Type'};
  346.     $DisplayType =        $hashref->{'DisplayType'};
  347.     $Usage         =         $hashref->{'Usage'};
  348.     $LocalName     =        $hashref->{'LocalName'};
  349.     $RemoteName =        $hashref->{'RemoteName'};
  350.     $Comment     =        $hashref->{'Comment'};
  351.     $Provider    =        $hashref->{'Provider'};
  352.  
  353.     $hashref = pack( 'i4 p4',$Scope,$Type,$DisplayType,$Usage,$LocalName,$RemoteName,$Comment,$Provider);
  354.  
  355.     $hashref;
  356.  
  357. }
  358.  
  359.  
  360. bootstrap Win32::NetResource;
  361.  
  362. # Preloaded methods go here.
  363.  
  364. # Autoload methods go after __END__, and are processed by the autosplit program.
  365.  
  366. 1;
  367. __END__
  368.