Network shares(n) 0.1 "Network share management"
Network shares - Functions related to management of network shares
package require twapi
This module provides commands related to management of Windows network shares
including file and print shares.
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.
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.
- 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 |
export, file shares, network shares, printer shares, shares
Copyright © 2003, Ashok P. Nadkarni