NetResource(3) User Contributed Perl Documentation NetResource(3)NAME
Win32::NetResource - manage network resources in perl
SYNOPSIS
use Win32::NetResource;
$ShareInfo = {
'path' => "C:\\MyShareDir",
'netname' => "MyShare",
'remark' => "It is good to share",
'passwd' => "",
'current-users' =>0,
'permissions' => 0,
'maxusers' => -1,
'type' => 0,
};
Win32::NetResource::NetShareAdd( $ShareInfo,$parm )
or die "unable to add share";
DESCRIPTION
This module offers control over the network resources of Win32.Disks,
printers etc can be shared over a network.
DATA TYPES
There are two main data types required to control network resources.
In Perl these are represented by hash types.
%NETRESOURCE
KEY VALUE
'Scope' => Scope of an Enumeration
RESOURCE_CONNECTED,
RESOURCE_GLOBALNET,
RESOURCE_REMEMBERED.
'Type' => The type of resource to Enum
RESOURCETYPE_ANY All resources
RESOURCETYPE_DISK Disk resources
RESOURCETYPE_PRINT Print resources
'DisplayType' => The way the resource should be displayed.
RESOURCEDISPLAYTYPE_DOMAIN
The object should be displayed as a domain.
RESOURCEDISPLAYTYPE_GENERIC
The method used to display the object does not matter.
RESOURCEDISPLAYTYPE_SERVER
The object should be displayed as a server.
RESOURCEDISPLAYTYPE_SHARE
The object should be displayed as a sharepoint.
'Usage' => Specifies the Resources usage:
RESOURCEUSAGE_CONNECTABLE
RESOURCEUSAGE_CONTAINER.
'LocalName' => Name of the local device the resource is
connected to.
'RemoteName' => The network name of the resource.
'Comment' => A string comment.
'Provider' => Name of the provider of the resource.
%SHARE_INFO
This hash represents the SHARE_INFO_502 struct.
KEY VALUE
'netname' => Name of the share.
'type' => type of share.
'remark' => A string comment.
'permissions' => Permissions value
'maxusers' => the max # of users.
'current-users' => the current # of users.
'path' => The path of the share.
'passwd' => A password if one is req'd
FUNCTIONS
NOTE
All of the functions return false if they fail.
GetSharedResources(\@Resources,dwType,\%NetResource = NULL)
Creates a list in @Resources of %NETRESOURCE hash references.
The return value indicates whether there was an error in accessing
any of the shared resources. All the shared resources that were
encountered (until the point of an error, if any) are pushed into
@Resources as references to %NETRESOURCE hashes. See example
below. The \%NetResource argument is optional. If it is not
supplied, the root (that is, the topmost container) of the network
is assumed, and all network resources available from the toplevel
container will be enumerated.
AddConnection(\%NETRESOURCE,$Password,$UserName,$Connection)
Makes a connection to a network resource specified by %NETRESOURCE
CancelConnection($Name,$Connection,$Force)
Cancels a connection to a network resource connected to local
device $name.$Connection is either 1 - persistent connection or 0,
non-persistent.
WNetGetLastError($ErrorCode,$Description,$Name)
Gets the Extended Network Error.
GetError( $ErrorCode )
Gets the last Error for a Win32::NetResource call.
GetUNCName( $UNCName, $LocalPath );
Returns the UNC name of the disk share connected to $LocalPath in
$UNCName. $LocalPath should be a drive based path. e.g.
"C:\\share\\subdir"
NOTE
$servername is optional for all the calls below. (if not given the
local machine is assumed.)
NetShareAdd(\%SHARE,$parm_err,$servername = NULL )
Add a share for sharing.
NetShareCheck($device,$type,$servername = NULL )
Check if a directory or a device is available for connection from
the network through a share. This includes all directories that
are reachable through a shared directory or device, meaning that if
C:\foo is shared, C:\foo\bar is also available for sharing. This
means that this function is pretty useless, given that by default
every disk volume has an administrative share such as "C$"
associated with its root directory.
$device must be a drive name, directory, or a device. For example,
"C:", "C:\dir", "LPT1", "D$", "IPC$" are all valid as the $device
argument. $type is an output argument that will be set to one of
the following constants that describe the type of share:
STYPE_DISKTREE Disk drive
STYPE_PRINTQ Print queue
STYPE_DEVICE Communication device
STYPE_IPC Interprocess communication (IPC)
STYPE_SPECIAL Special share reserved for interprocess
communication (IPC$) or remote administration
of the server (ADMIN$). Can also refer to
administrative shares such as C$, D$, etc.
NetShareDel( $netname, $servername = NULL )
Remove a share from a machines list of shares.
NetShareGetInfo( $netname, \%SHARE,$servername=NULL )
Get the %SHARE_INFO information about the share $netname on the
server $servername.
NetShareSetInfo( $netname,\%SHARE,$parm_err,$servername=NULL)
Set the information for share $netname.
EXAMPLE
Enumerating all resources on the network
#
# This example displays all the share points in the entire
# visible part of the network.
#
use strict;
use Win32::NetResource qw(:DEFAULT GetSharedResources GetError);
my $resources = [];
unless(GetSharedResources($resources, RESOURCETYPE_ANY)) {
my $err;
GetError($err);
warn Win32::FormatMessage($err);
}
foreach my $href (@$resources) {
next if ($$href{DisplayType} != RESOURCEDISPLAYTYPE_SHARE);
print "-----\n";
foreach( keys %$href){
print "$_: $href->{$_}\n";
}
}
Enumerating all resources on a particular host
#
# This example displays all the share points exported by the local
# host.
#
use strict;
use Win32::NetResource qw(:DEFAULT GetSharedResources GetError);
if (GetSharedResources(my $resources, RESOURCETYPE_ANY,
{ RemoteName => "\\\\" . Win32::NodeName() }))
{
foreach my $href (@$resources) {
print "-----\n";
foreach(keys %$href) { print "$_: $href->{$_}\n"; }
}
}
AUTHOR
Jesse Dougherty for Hip Communications.
Additional general cleanups and bug fixes by Gurusamy Sarathy
<gsar@activestate.com>.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 135:
'=item' outside of any '=over'
Around line 153:
You forgot a '=back' before '=head1'
perl v5.14.2 2005-09-17 NetResource(3)
