Tcl Windows API extension

A Lan Manager (LM) session is a logical connection between the client and server over which all communications related to shares takes place. LM sessions are created and terminated on the fly by the client as and when needed.

Lan Manager sessions on a server can be enumerated through the find_lm_sessions command. Information about individual sessions can be obtained through the get_lm_session_info command. Existing sessions can be deleted using end_lm_sessions.

The files and resource opened within a Lan Manager session can be enumerated through the find_lm_open_files command. Information about individual open files can be obtained through get_lm_open_file_info and closed using close_lm_open_file.

Information about the connections to a shared resource on a system can be obtained through find_lm_connections.

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_client_shares lists all current connections to any network share. Details about a particular connected share can be obtained through the get_client_share_info command.

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.

Share Types

The type of a network share is indicated by a token that indicates the basic type, such as file or print queue, followed by one or more tokens that indicate additional attributes such as whether it is a temporary share. The basic share type token is one of file, print, ipc or device corresponding to a file, print queue, interprocess communication, and a communication device respectively. Additional type information may contain the tokens temporary, which indicates a temporary share, and special, which indicates a administrative share.

Commands

close_lm_open_file FILEID ?-system SYSTEMNAME?

Closed the file or resource associated with FILEID. The file ids open within a Lan Manager session may be obtained through the find_lm_open_files command. Option -system may be specified to indicate the system on which the command is to be executed. By default, this is the local system.

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), file 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 2000. An error will be 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.

Example: Map a drive to a network share

delete_share SHARENAME ?-system SYSTEMNAME?

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

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.

end_lm_sessions ?options?

Terminates all Lan Manager sessions matching the specified options. options may include the following matching criteria:

-system SYSTEMNAME	Specifies the name of the system on which the command is to be executed. By default, this is the local system.
-client SYSTEMNAME	Specifies the name of the client system whose sessions are to be terminated.
-user USERNAME	Specifies the name of the user whose sessions are to be terminated.

Note that at least one of the options -user or -client must be specified.

find_lm_connections ?options?

Returns information about the connections to a share on a server or established from a particular client system. The return value is a list of sublists containing information about each connection. The actual data included depends on the options specified.

-activeseconds	Returns the number of seconds the connection has been established.
-all	Returns all data fields for each connection.
-client CLIENTNAME	Specifies that only connections from client CLIENTNAME should be included in the returned list. This option and option -share are mutually exclusive.
-clientname	Returns the name of the client computer for the connection.
-id	Returns the connection id.
-opencount	Returns number of resources currently opened through the connection.
-share SHARENAME	Specifies that only connections to the share identified by SHARENAME should be included in the returned list. This option and option -client are mutually exclusive.
-sharename	Returns the name of the share to which the connection is attached.
-system SYSTEMNAME	Specifies the name of the system on which the command is to be executed. By default, this is the local system.
-type	Returns the share type of the resource to which the connection is made (see Share Types).
-usercount	Returns number of users currently using the connection.
-username	Returns name of the user that made the connection.

find_lm_open_files ?options?

Returns a list of sublists containing information about files and devices opened through a Lan Manager session. The actual data included depends on the options specified.

The following options specify matching criteria that control which sessions are returned:

-system SYSTEMNAME	Specifies the name of the system on which the command is to be executed. By default, this is the local system.
-basepath PATHPREFIX	Specifies that all returned files should have begin with PATHPREFIX. If PATHPREFIX is an empty string (default), all open files are included.

Additional options control the data returned for each open file. Refer to get_lm_open_file_info for a list of these options.

find_lm_sessions ?options?

Returns a list of Lan Manager sessions matching the specified options. The list contains sublists containing data for each session. The actual data included depends on the options specified.

The following options specify matching criteria that control which sessions are returned:

-system SYSTEMNAME	Specifies the name of the system on which the command is to be executed. By default, this is the local system.
-client SYSTEMNAME	Specifies the name of the client system whose sessions are to be included. If SYSTEMNAME is an empty string (default), all client systems are included.
-user USERNAME	Specifies the name of the user whose sessions are to be included. If USERNAME is an empty string (default), all users are included.

Additional options control the data returned for each session. Refer to get_lm_session_info for a list of these options.

get_client_share_info SHAREPATH ?options?

Returns information about the connected network share identified by SHAREPATH. SHAREPATH may be either a UNC format share or a locally mapped device.

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

-all	Returns all configuration data for the connected share.
-comment	Returns the comment describing the connected share, if any
-domain	Returns the domain name of the connected share.
-localdevice	Returns the local device to which the share is mapped and an empty string otherwise.
-opencount	Returns the number of open handles that are open to resources on the remote share.
-provider	Returns the name of the network service provider that owns the share.
-remoteshare	Returns the name of the remote share.
-status	Returns the status of the share. This may be one of connected, paused, lostsession, disconnected, networkerror, connecting, reconnecting or unknown.
-type	Returns the type of the network share. This may be one of file, printer, char, ipc or unknown.
-usecount	Returns the number of references to the remote share. Note the remote share may be connected multiple times with and without local device mappings.
-user	The name of the user who initiated the connection.

get_client_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.

Example: List connected shares

get_mapped_share_info SHAREPATH ?options?

This command is now deprecated. Use get_client_share_info instead.

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 configuration 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

Example: Show mapped drive information

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 configuration 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.

Example: List shares exported from a system

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. SHARETYPE must be one of base share types listed in Share Types. By default, all share types are enumerated.
-excludespecial	Specifying this option causes special shares (see Share Types) not to be included in the enumeration.

Example: List shares exported from a system

get_lm_open_file_info FILEID ?options?

Returns a list of field values pairs containing data for a file or resource opened in a Lan Manager session. The file is identified by FILEID. find_lm_open_files returns a list of all such ids. The command will generate an error there is no file open with the specified id.

The actual data returned depends on the options specified. The following options may be specified:

-system SYSTEMNAME	Specifies the name of the system on which the command is to be executed. By default, this is the local system.
-all	Returns all data fields.
-id	Returns the file id of the open resource.
-lockcount	Returns the number of locks on the open resource.
-path	Returns the path of the open resource.
-permissions	Returns a list of zero or more from among read, write and create corresponding to the access permissions for the opening application.
-username	Returns the name of the user that opened the resource.

get_lm_session_info CLIENTSYSTEM USER ?options?

Returns a list of field values pairs containing data for a Lan Manager session. The Lan Manager session is identified by CLIENTSYSTEM which identifies a client system and USER which identifies the user that authenticated the session. The actual data returned depends on the options specified. The command will generate an error if no matching connection is found.

The following options may be specified:

-system SYSTEMNAME	Specifies the name of the system on which the command is to be executed. By default, this is the local system.
-all	Returns all data fields.
-activeseconds	Returns the number of seconds session has been active.
-attrs	Returns a list of tokens describing the session attributes. The tokens may include guest, indicating the session was established using a guest account, and noencryption, indicating the session was established without using password encryption.
-clientname	Returns the UNC name of the client system.
-clienttype	Returns a string identifying the type of client system.
-idleseconds	Returns the number of seconds the session has been idle.
-opencount	Returns the number of open files, devices and pipes opened in the session.
-transport	Returns the name of the underlying transport over which the session runs.
-username	Returns the name of the user account under which the session was established.

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. If unspecified or empty, this defaults to the share name.
-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. If unspecified, it defaults to allowing group Everyone (well-known SID S-1-1-0) read access similar to default permissions when creating a share from Windows Explorer.
-type SHARETYPE	Specifies the type of the share. See Share Types for details. This defaults to a file share.

Example: Export a network 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 STRING	Sets the comment associated with the share.
-max_conn INTEGER	Sets the maximum number of connections that are permitted for the share. A value of -1 indicates that there is not limit.
-secd SECD	Sets the security descriptor attached to the share.

Network shares and Lan Manager

SYNOPSIS

DESCRIPTION

Lan Manager sessions

Network Shares - Server

Network Shares - Client

Share Types

Commands

COPYRIGHT

TWAPI 2.2.3 Documentation