Network shares(n) 0.1 "Network share management"

NAME

Network shares - Functions related to management of network shares

SYNOPSIS

package require twapi

new_share SHARENAME RESOURCE ?options?
delete_share ?-system SYSTEMNAME?
get_shares ?options?
get_share_info SHARENAME ?options?
set_share_info SHARENAME ?options?
get_connected_shares
connect_share SERVERSHARE ?options?
disconnect_share SHARE ?options?
get_mapped_share_info SHAREPATH ?options?

DESCRIPTION

This module provides commands related to management of Windows network shares including file and print shares.

Network Shares - Server

These commands work with all types of Windows network shares exported from a server including files and disks, printers, devices and IPC.

The command new_share creates a new share of the specified type. The command delete_share removes an existing share.

The commands get_shares and get_share_info allow enumeration and retrieval of detailed information about a share. The command set_share_info allows attributes of an existing share to be modified.

Network Shares - Client

The following commands deal with client side of network share connections.

The commands connect_share and disconnect_share are used to establish and remove client side connections to network shares. The command get_connected_shares lists all current connections to any network share.

When a local device (for example, a printer port or a drive letter) is mapped to a network drive, information about the mapping may be obtained through the get_mapped_share_info command.

Commands

new_share SHARENAME RESOURCE ?options?
Creates a new share with name SHARENAME that exports the specified resource RESOURCE. Unless specified through the -type option, the share is assumed to be a file share and RESOURCE is assumed to be the directory path.

The following options control the various attributes of the share:

-system SYSTEMNAME
Specifies the name of the system on which the share is to be created. By default, this is the local system.

-comment COMMENT
Specifies a comment to be associated with the share. This is displayed to users connecting to the share.

-max_conn MAX_NUM_CONNECTION
Specifies the maximum number of connections to be allowed. If this is not specified, or is specified as -1, there is no limit to the number of connections allowed to the share.

-secd SECURITY_DESCRIPTOR
Specifies the security descriptor to be attached to the share.

-type SHARETYPE
Specifies the type of the share. See Share Types for details. This defaults to a file share.


delete_share ?-system SYSTEMNAME?
Deletes a share. By default the share is assumed to be on the local system unless the -system option is specified.

get_shares ?options?
This command enumerates all the shares exported on a system. The following options control the shares that are enumerated.

-system SYSTEMNAME
Specifies the name of the system whose shares are to be enumerated. By default, this is the local system.

-type SHARETYPE
Specifies the type of the share to include in the enumeration. See Share Types for details. By default, all share types are enumerated.

-excludespecial
Specifying this option causes special shares (see Share Types not to be included in the enumeration.


get_share_info SHARENAME ?options?
Retrieves information pertaining to the specified share. By default, the share is assumed to be on the local system. The -system may be used to specify the name of a remote system.

The information returned depends on the specified options and is in the form of a flat list of "option value" pairs.

-all
Returns all configuation data for the share.

-name
Returns the name of the share as configured. This is generally SHARENAME but may differ in the character case.

-type
Returns the type of the share. See Share Types for details.

-path
Returns the path or name of the resource being shared.

-comment
Returns the comment associated with the share.

-max_conn
Returns the maximum number of connections that are permitted for the share. A value of -1 indicates that there is no limit.

-current_conn
Returns the current number of connections to the share.

-secd
Returns the security descriptor attached to the share.


set_share_info SHARENAME ?options?
Changes the configuration of the specified share. By default, the share is assumed to be on the local system. The -system may be used to specify the name of a remote system.

The configuration data that is to be modified is specified through the following options:

-comment
Sets the comment associated with the share.

-max_conn
Sets the maximum number of connections that are permitted for the share. A value of -1 indicates that there is not limit.

-secd
Sets the security descriptor attached to the share.


get_connected_shares
Returns a list of currently connected network shares. The returned list consists of sublists corresponding to each connected network share. The first element of each sublist is the local device (for example X:). This may be an empty string if the connection has not been mapped to a local device. The second element of the sublist is the name of the server share for the connection.

connect_share SERVERSHARE ?options?
Establishes a new connection to a network share, optionally mapping it to a local device. SERVERSHARE is of the form \\SERVERNAME\SHARE and is the name of the share to connect to. The following options may be specified to control the connection characterisics:

-type
Specifies the type of network share. This must be one of any (default), disk for file and disk shares or printer for print shares.

-localdevice DEVICENAME
By default, the command establishes a connection to SERVERSHARE but does not map it to a local device. Specifying this option maps the network share connection to a local device, for example a drive letter or printer port.

Note that if this option is specified, the -type option must also be specified with a value of disk or printer.

-provider PROVIDERNAME
This option allows specification of a network provider to be used for the connection. Generally, this option should not be specified allowing Windows to select the appropriate network provider based on SERVERSHARE.

-user USERNAME
Specifies the user account to use to connect to the network share. By default, this is the current user account.

-password PASSWORD
Specifies the password to be used for connecting to the network share. This option is ignored if either -defaultpassword or -nopassword is specified.

-defaultpassword
Specifies that the password for the current user account is to be used for connecting. This option cannot be used with the -nopassword option.

-nopassword
Specifies that no password is to be used for connecting. This option cannot be used with the -defaultpassword option.

-interactive
Specifies that a user name and password dialog should be displayed to the user if the network share login fails. The connection is retried using the values entered by the user.

-prompt
Displays a dialog allowing the user to change the user name and password before the connection attempt is made. This option has no effect if -interactive is not specified.

-commandline
If this option is specified, the operating system will prompt the user for the password on the command line rather than showing the password dialog. This option has no effect if -interactive is not specified. This option is not supported on Windows NT 4.0 and Windows 2000. An error will generated if this option is specified on those platforms.

-window HWIN
Specifies that the window identified by HWIN is to be used as the owner window for any password dialogs that are displayed.

-updateprofile
If this option is specified, the user's profile is updated so that the network share connection will be reestablished every time the user logs in.


disconnect_share SHARE ?options?
Disconnects the network share SHARE. The following options may be specified:

-force
Forces the network share connection to be closed even if there are open files or print jobs on the connection.

-updateprofile
If this option is specified, the user's profile is updated so that the network share connection will not be reestablished every time the user logs in.


get_mapped_share_info SHAREPATH ?options?
Retrieves various information about a network share. SHAREPATH can be any path under a network share but the path must begin with the local device name, for example C:, if it was mapped to a local device and the share name, for example, \\SERVERNAME\SHARENAME, if no local device was mapped to it.



The information returned depends on the specified options and is in the form of a flat list of "option value" pairs.

-all
Returns all configuation data for the share connection.

-user
Returns the user account name under which the connection was established.

-uncpath
Returns the UNC format path corresponding to SHAREPATH

-uncvolume
Returns the UNC format name of the server share

-relative_path
Returns the relative path component of SHAREPATH under the server share.


For example, assume \\myfileserver\userdata is mapped to drive X:. Then the command

 
twapi::get_mapped_share_info X:\dir\file -uncpath -uncvolume -relativepath

will return

 
-uncpath \\myfileserver\userdata\dir\file -uncvolume \\myfileserver\userdata -relativepath \dir\file

KEYWORDS

export, file shares, network shares, printer shares, shares

COPYRIGHT

Copyright © 2003, Ashok P. Nadkarni