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 via the LANMAN protocol. Some comThey do not work with shares implemented with other protocols such as DFS.

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. Note that some commands will only work with LANMAN shares. They do not work with shares implemented with other protocols such as DFS.

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_client_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 command returns the path through which the share should be accessed. If the -localdevice option (see below) is specified, this is the local device the share is mapped to. Otherwise, it is the UNC share path.

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. DEVICENAME may also be specified as * in which case the system will choose a drive letter to be mapped. 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. PASSWORD but should be in encrypted form as returned by by the read_credentials or conceal commands. 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.
-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.

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 record array whose fields correspond to the options below.

-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.
-user	Returns name of the user that made the connection.

find_lm_open_files ?options?

Returns a record array containing information about files and devices opened through a Lan Manager session. The fields of the record array depend on the specific options. Refer to get_lm_open_file_info for a list of these options.

In addition, the following options specify matching criteria that control which records are returned:

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

find_lm_sessions ?options?

Returns a record array of Lan Manager sessions matching the specified options. The fields of the record array depend on the options specified. Refer to get_lm_session_info for a list of these options.

In addition, the following options specify matching criteria that control which sessions are returned:

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

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

-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 ?options?

Returns a list of network shares to which a system is currently connected.

-system SYSTEMNAME	Specifies the name of the system whose shares are to be enumerated. By default, this is the local system.
-level LEVEL	Specifies the level of detail to be returned (see below).

If the -level option is not specified, the returned list contains the paths of the remote server shares.

If -level is specified, the command returns a record array whose fields depend on LEVEL as follows:

0	-localdevice, -remoteshare
1	The fields for level 0 plus -type, -opencount, -status, -usecount.
2	The fields for level 1 plus -domain, -user.

Refer to get_client_share_info for a description of these fields.

This command only returns LANMAN shares, not shares through other network providers such as DFS or WebDAV. Use wnet_connected_resources to retrieve shared exported through all providers.

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

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

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.
-level LEVEL	Specifies the level of detail to be returned (see below).
-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.

If the -level option is not specified, the command returns a list of share names. If -level is specified the command returns a record array whose fields depend on LEVEL as follows:

0	-name
1	Fields at level 0 plus -comment, -type
2	Fields at level 1 plus -current_conn, -max_conn, -name, -passwd, -path, -permissions, -comment, -type.
502	Fields at level 2 plus -reserved, and -secd.

See get_share_info for explanation of these fields.

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

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.

wnet_connected_resources ?-type file|printer?

Returns a list of connected network resources. Without any options specified, all connected network resources are returned. The option -type may be specified to only return file or printer network resources.

The returned value is a list consisting of pairs. The first element of each pair is the local device, if any, associated with the remote resource and the second is the path of the remote resource.

Network shares and Lan Manager

SYNOPSIS

DESCRIPTION

Lan Manager sessions

Network Shares - Server

Network Shares - Client

Share Types

Commands

COPYRIGHT

TWAPI 4.5.2 Documentation