The Win32 Network Management APIs 8

 

 

 

 

 

Session Functions

 

The network management session functions control network sessions established between workstations and servers. The functions require that the server service be started on the server. The session functions are listed following.

 

Function

Description

NetSessionDel()

Deletes the current connections between a workstation and server; terminates the network session.

NetSessionEnum()

Returns information about all current sessions established for a server.

NetSessionGetInfo()

Returns information about a particular session.

 

A session is a link between a workstation and a server. A session is established the first time a workstation makes a connection to a shared resource on the server. Until the session ends, all further connections between the workstation and the server are part of the same session. To end a session, an application on the server end of a connection calls the NetSessionDel() function. The network management session functions manage information on a per-user basis with the username parameter. Because there can be multiple users per session, this parameter is necessary to access the user-specific information for the session. Session functions are available at the following information levels:

 

  1. SESSION_INFO_0
  2. SESSION_INFO_1
  3. SESSION_INFO_2
  4. SESSION_INFO_10
  5. SESSION_INFO_502

 

If you are programming for Active Directory, you may be able to call certain Active Directory Service Interface (ADSI) methods to achieve the same functionality you can achieve by calling the network management session functions.

 

Share Functions

 

The network management share functions control shared resources. A shared resource is a local resource on a server (for example, a disk directory, print device, or named pipe) that can be accessed by users and applications on the network. The share functions are listed following.

 

Function

Description

NetShareAdd()

Shares a resource on a server.

NetShareCheck()

Queries whether a server is sharing a device.

NetShareDel()

Deletes a share name from a server's list of shared resources.

NetShareEnum()

Retrieves share information about each shared resource on a server.

NetShareGetInfo()

Retrieves information about a specified shared resource on a server.

NetShareSetInfo()

Sets a shared resource's parameters.

 

These share function apply only to shares on a Server Message Block (LAN Manager) server. These share functions do not support Distributed File System (DFS) shares. For example, the NetShareGetInfo() function can only retrieve information for a specified share resource on an SMB Server. To retrieve information for a share using a different network provider (WebDAV or a DFS share, for example), use the WNetGetConnection() function. The NetShareAdd() function allows a user or application to share a resource of a specific type using the specified share name. The NetShareAdd() function requires the share name and local device name to share the resource. A user or application must have an account on the server to access the resource. You can also specify a security descriptor to be associated with a share. Security descriptors specify which users are allowed to access files through the share, and with what type of access. Specify a SECURITY_DESCRIPTOR with the SHARE_INFO_502 information level when calling NetShareAdd() or NetShareSetInfo(). NetShareSetInfo() supports the SHARE_INFO_1501 information level. The network management functions use the following special share names for interprocess communication (IPC) and remote administration of the server:

 

  1. IPC$, reserved for interprocess communication
  2. ADMIN$, reserved for remote administration
  3. A$, B$, C$ (and other local disk names followed by a dollar sign), assigned to local disk devices

 

To list all connections made to a shared resource on a server, or to list all connections established from a particular computer, call the NetConnectionEnum() function. You can call NetConnectionEnum() at the CONNECTION_INFO_0 and CONNECTION_INFO_1 information levels. Share functions are available at the following information levels although some share levels are only applicable to some of the share functions:

 

  1. SHARE_INFO_0
  2. SHARE_INFO_1
  3. SHARE_INFO_2
  4. SHARE_INFO_501
  5. SHARE_INFO_502
  6. SHARE_INFO_503
  7. SHARE_INFO_1004
  8. SHARE_INFO_1005
  9. SHARE_INFO_1006
  10. SHARE_INFO_1501

 

If you are programming for Active Directory, you may be able to call certain Active Directory Service Interface (ADSI) methods to achieve the same functionality you can achieve by calling the network management share functions.

 

Statistics Functions

 

The Windows operating system accumulates a set of operating statistics for workstations and servers from the time that the workstation or server service is started. To retrieve these statistics, you can call the following network management statistics function.

 

Function

Description

NetStatisticsGet()

Retrieves operating statistics for a service; supports the workstation and server services.

 

The NetStatisticsGet() function returns a STAT_WORKSTATION_0 structure when workstation statistics are requested; the function returns a STAT_SERVER_0 structure when server statistics are requested.

 

Use Functions

 

The network management use functions examine and manage connections (uses) between workstations and servers. The use functions are listed following.

 

Function

Description

NetUseAdd()

Creates a connection between a local computer and a server.

NetUseDel()

Ends a connection to a shared resource.

NetUseEnum()

Lists all current connections between the local computer and resources on remote servers.

NetUseGetInfo()

Returns information about a connection to a shared resource.

 

These functions apply only to the Server Message Block (LAN Manager Workstation) client. The NetUseGetInfo() function does not support Distributed File System (DFS) shares. To retrieve connection information for a shared resource using a different network provider (WebDAV or a DFS share, for example), use the WNetGetConnection() function.

Connections are distinguished from sessions: a session is established the first time a workstation makes a connection to a shared resource on the server. All additional connections between the workstation and the server are part of this same session until the session ends. Two types of connections can be made: device-name connections (which can only be explicit) and universal-naming convention (UNC) connections (which can be explicit or implicit).

Connections are made on a per-user basis. A connection made by a user is deleted when that user logs off. For this reason the network management use functions are local only, because a connection set up by a remote user would not be accessible to any other users, even the user that was interactively logged on to that computer. The NetUseAdd() function establishes an explicit connection between the local computer and a resource shared on a server by redirecting a local device name to the share name of a remote server resource (\\servername\sharename). Once a device-name connection is made, users or applications can use the remote resource by specifying the local device name. Implicit UNC connections are made by the function responsible for the connection. To establish an implicit UNC connection, an application passes the share name of a resource to any function that accepts UNC paths. The function accepts the UNC name and makes a connection to the specified share name. All further requests on this connection require the full share name. The use functions are available at the following information levels:

 

  1. USE_INFO_0
  2. USE_INFO_1
  3. USE_INFO_2

 

User Functions

 

The network management user functions control a user's account in the security database, which is the security accounts manager (SAM) database or, in the case of domain controllers, the Active Directory. The user functions are listed following.

 

Function

Description

NetUserAdd()

Adds a user account and assigns a password and privilege level.

NetUserChangePassword()

Changes a user's password for a specified network server or domain.

NetUserDel()

Deletes a user account from the server.

NetUserEnum()

Lists all user accounts on a server.

NetUserGetGroups()

Returns a list of global group names to which a user belongs.

NetUserGetInfo()

Returns information about a particular user account on a server.

NetUserGetLocalGroups()

Returns a list of local group names to which a user belongs.

NetUserSetGroups()

Sets global group memberships for a specified user account.

NetUserSetInfo()

Sets the password and other elements of a user account.

 

Each user or application that accesses network resources must have an account in the security database. The directory services use this account to verify that the user or application has permission to connect to a resource. When a user or an application requests access to a resource, the Windows security system checks for an appropriate user account or group account to permit the access. Once you remove a user account by calling the NetUserDel() function, the user can no longer access the server except by using the guest account. Because a user's password is confidential, it is not returned by the NetUserEnum() function or the NetUserGetInfo() function. The password is initially assigned when you call NetUserAdd(). User account information is available at the following levels:

 

  1. USER_INFO_0
  2. USER_INFO_1
  3. USER_INFO_2
  4. USER_INFO_3
  5. USER_INFO_4
  6. USER_INFO_10
  7. USER_INFO_11
  8. USER_INFO_20
  9. USER_INFO_21
  10. USER_INFO_22
  11. USER_INFO_23

 

In addition, the following information levels are valid when you call the NetUserSetInfo() function:

 

  1. USER_INFO_1003
  2. USER_INFO_1005
  3. USER_INFO_1006
  4. USER_INFO_1007
  5. USER_INFO_1008
  6. USER_INFO_1009
  7. USER_INFO_1010
  8. USER_INFO_1011
  9. USER_INFO_1012
  10. USER_INFO_1014
  11. USER_INFO_1017
  12. USER_INFO_1020
  13. USER_INFO_1024
  14. USER_INFO_1051
  15. USER_INFO_1052
  16. USER_INFO_1053

 

The following functions enable applications to check password compliance.

 

Function

Description

NetValidatePasswordPolicyFree()

Frees the memory allocated by the NetValidatePasswordPolicy() function.

NetValidatePasswordPolicy()

Verifies that passwords meet complexity, aging, minimum length, and history reuse requirements.

 

If you are programming for Active Directory, you may be able to call certain Active Directory Service Interface (ADSI) methods to achieve the same functionality you can achieve by calling the network management user functions.

 

 

 

 

< Win32 Network Management APIs 7 | Win32 Network Management APIs | Win32 Programming | Win32 Network Management APIs 9 >