Win32::NetResource

The Win32::NetResource module allows you to manage shared resources on a network, such as printers, disks, etc. Two data structures are used to provide or store information for many of the NetResource functions. The first is the share_info hash. This hash contains parameters for setting up a share, using the following structure:

%share_info = ( netname => "name of share", type => "type of share", remark => "a string comment", permissions => "permissions value", maxusers => "the max number of users", current-users => "the current number of users", path => "the path of the share", passwd => "password, if required" );

A netresource data structure contains information about the shared resource or device. It has the following structure:

%netresource = ( 'Scope' => "Scope of a resource connection (see list below for  values)", 'Type' => "The type of resource (see list below)", 'DisplayType' => "How the resource should be displayed (see list  below)", 'Usage' => "How the resource should be used", 'LocalName' => "Name of the local device the resource is connected  to", 'RemoteName' => "Network name of the resource", 'Comment' => "Comment string", 'Provider' => "Provider of the resource" );

The first three elements of the netresource hash contain values described in the following lists. The Scope value can be one of the following:

• RESOURCE_CONNECTED
• Resource is already connected
• RESOURCE_REMEMBERED
• Resource is reconnected each time the user logs on
• RESOURCE_GLOBALNET
• Resource is available to the entire network

The Type element takes one of the following values:

• RESOURCETYPE_ANY
• All resources
• RESOURCETYPE_DISK
• Disk resources
• RESOURCETYPE_PRINT
• Print resources

The Display element can be one of these values:

• RESOURCEDISPLAYTYPE_DOMAIN
• Object is displayed as a domain
• RESOURCEDISPLAYTYPE_SERVER
• Object is displayed as a server
• RESOURCEDISPLAYTYPE_SHARE
• Object is displayed as a sharepoint
• RESOURCEUSAGE_CONNECTABLE
• Resource can be connected to a local device
• RESOURCEUSAGE_CONTAINER
• Resource contains more resources

The functions in Win32::NetResource use the share_info and netresource structures as input and output arguments. These arguments are used in the description of the functions below; you should name them whatever you want.

AddConnection (\%netresource, password, username, connection) 

Connects to the resource described in %netresource, with the password and username of the user. The <connection> flag indicates whether the connection should be remembered for the user for all logins.

CancelConnection (name, connection, force) 

Cancels a connection to a resource connected to the local device specified by name. connection indicates the type of connection, with being a persistent connection and being nonpersistent. The force value is a Boolean indicating whether to force the connection.

GetError ($code) 

Gets the last error caused by a Win32 network call and saves it in the variable named by code.

GetSharedResources (\@resources, type) 

Gets a list of all network resources and saves the list as references to %netresource hashes in @resources. type is the type of enumeration.

GetUNCName ($uncname, path) 

Gets the UNC name of the share connected to the local path and saves it to the variable specified by uncname.

NetShareAdd (\%shareinfo, $error, [server]) 

Makes a disk resource described by shareinfo available for sharing on the network. server is the name of the server for the shared resource (local is assumed if not specified). Any error that occurs is saved in the variable named by error.

NetShareCheck (device, $type, [server]) 

Returns true if a share on device is available for connection. The type of share is saved in the variable named by type (if the function returns true).

NetShareDel (name, [server]) 

Removes the share named name on optional server from a machine's list of shares.

NetShareGetInfo (name, \%shareinfo, [server]) 

Gets the share information for the share name on optional server and saves it in the specified shareinfo variable.

NetShareSetInfo (name, \%shareinfo, $error, [server]) 

Sets the information for the share name on server to the parameters given by shareinfo. The error status is saved to the variable named by error.

WNetGetLastError ($code, $description, $name) 

Gets the extended network error and saves its information to the variables named by code, description, and name. An extended network error is given only when Win32::GetLastError returns ERROR_EXTENDED_ERROR.