Network Management

Microsoft® Windows NT®, Windows® 2000, Windows® 95, and Windows® 98 support a variety of networking APIs. The network management functions provide the ability to manage user accounts and network resources. Many of the capabilities provided by the network management functions are not provided by other networking functions. However, if the capabilities are provided by another set of functions, the documentation for the network management functions will refer you to other functions you can use for the same task.

  • About Network Management
  • Using Network Management
  • Network Management Reference
Microsoft Platform SDK, February 2001 Edition.
This content last built on Thursday, February 01, 2001.


About Network Management

The network management functions allow you to manage network shares as Windows Explorer and the Net command do. You can also manage user accounts as User Manager does. For more information, see the following topics:

  • Network Management Function Groups
  • Network Management Data
  • Platform Support
  • Security Requirements for the Network Management Functions
  • Using Network Management
  • Network Management Reference


Network Management Function Groups

The network management functions can be divided into the following groups:

  • Access functions (Windows 95 and Windows 98 only)
  • Alert functions
  • ApiBuffer functions
  • Directory Service functions
  • Distributed File System (Dfs) functions
  • Get functions
  • Group functions
  • Local group functions
  • Message functions
  • NetFile functions
  • Remote Utility functions
  • Replicator functions
  • Schedule functions
  • Server functions
  • Server and workstation transport functions
  • Session functions
  • Share functions
  • Statistics functions
  • Use functions
  • User functions
  • User modal functions
  • Workstation and workstation user functions

If you are programming for Active Directory™, you may be able to call certain ADSI interface methods to achieve the same functionality you can achieve by calling certain network management functions. For more information, see Mapping ADSI Interfaces to the Network Management Functions.

The system also provides a network-independent set of network functions (WNet functions) that allow network functions to work across different network vendors' products. If your application could be converted to use a WNet function, you should perform the conversion. There are at least two reasons to make the change:

  1. The WNet functions are network independent, while the network management functions work only on Microsoft networks.
  2. Some of the Win32 functions documented in this SDK may not be supported in future releases of Microsoft operating systems if they have been superseded. Microsoft does not plan to remove specific functions unless equivalent or better functionality is available.

Windows NT/2000 or later: The following groups of network management functions are obsolete on this platform:

  • Access functions
  • Audit functions
  • Configuration functions
  • Error Logging functions
  • NetService functions


Access Functions

Windows NT/2000 or later: The access functions are obsolete on Windows NT/Windows 2000. These functions work only when the function is accessed with a LAN Manager 2.x system. The Win32 API provides a full set of access control functions. Use these in place of the network management access functions.

Windows 95/98/Me: The access functions examine or modify user or group access permissions for particular network resources. An access-control list (ACL) contains the name of a resource, an audit attribute field, and a list of access-control entries. An access-control entry (ACE) is a user name or a group name, and the corresponding access permissions.

The access functions that are supported on Windows 95 and Windows 98 are listed following.

Function | Description
NetAccessAdd | Creates a new ACL for a resource and sets the user or group access permissions.
NetAccessCheck | Verifies whether a user has permission to perform a specified operation on a particular resource.
NetAccessDel | Deletes the ACL for a resource.
NetAccessEnum | Retrieves information about all ACLs.
NetAccessGetInfo | Returns the ACL for a particular resource.
NetAccessGetUserPerms | Returns a user's or group's access permissions for a particular resource.
NetAccessSetInfo | Changes the ACL for a resource and grants access permissions.
NetSecurityGetInfo | Returns access control information in a security_info_1 structure.

Only users or applications with admin group membership or special permission for the resource can define or examine access permissions. Users have special permissions for a resource when they are granted ACCESS_PERM permission for that resource; this is also known as P permission.

Access permission information is available at the following levels:

access_info_0
access_info_1

Access list information is available at the following level:

access_list


Alert Functions

The network management alert functions notify network service programs and applications of network events. An event is a particular instance of a process, occurrence, or state of hardware as defined by an application. The alert functions allow applications to indicate when predefined events occur.

The alert functions are listed following.

Function | Description
NetAlertRaise | Notifies all registered clients that a particular event has occurred.
NetAlertRaiseEx | Simplifies notifying registered clients that a particular event has occurred, because, unlike NetAlertRaise, NetAlertRaiseEx does not require a STD_ALERT structure.

The alerter service must be running on the client computer when you call the NetAlertRaise function or the NetAlertRaiseEx function. If the service is not running, the functions fail with ERROR_FILE_NOT_FOUND. The alerter service on the client calls the NetMessageBufferSend function to send information to recipients.

Applications, network services, and internal network components use the network management alert functions to raise an alert, notifying various applications or users when a particular type of event occurs. The alert category functions, data types, structures, and constants are defined in the LMCONS.H, LMERR.H, and LMALERT.H header files. To access these definitions, define the constants INCL_NETERRORS and INCL_NETALERT, and include the header file LM.H.

The LMALERT.H file predefines the following alert classes (types of network events) for sending alerts:

  • Network events requiring administrative assistance
  • Addition of an entry to an error log file
  • Reception of a broadcast message by a user or an application
  • Completion of a print job
  • Use of certain applications or resources by users

You can define other classes of alerts for network applications as needed. For example, if an application on a server routinely writes large amounts of data to a disk drive, the application runs the risk of filling the disk. In this case, you might want to add the event "no free disk space'' to trigger an alert that notifies the application to pause or to terminate the process that is filling the disk. The event name for an alert can be any text string.

When you raise an alert with a call to the NetAlertRaise function, the message data should consist of one STD_ALERT header structure, followed by additional fixed-length data that is alert-specific in one ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, or USER_OTHER_INFO structure. Additional variable-length data can follow the alert-specific structure. (Calls to the NetAlertRaiseEx function do not require a STD_ALERT structure.) The calling application must allocate the memory for all structures and variable-length data, and free the memory after the call returns.

The following macros are available for use with alert data buffers.

Macro | Description
ALERT_OTHER_INFO | Returns a pointer to the fixed-length data that follows the STD_ALERT structure in an alert message.
ALERT_VAR_DATA | Returns a pointer to the variable-length data that follows the alert-specific data in an alert message.

Instead of using the network management alert functions, you may be able to use the Windows Management Instrumentation (WMI) SDK for event notification. For more information about the platforms that support the WMI event model, see Event Notification Support in the WMI documentation.


ApiBuffer Functions

The network management ApiBuffer functions are used to manage memory allocation. However, in general, you should use the memory management functions provided by the Win32 API.

The ApiBuffer functions are listed following.

Function | Description
NetApiBufferAllocate | Allocates memory from the heap. Call this function when you require compatibility with the NetApiBufferFree function.
NetApiBufferFree | Frees memory allocated by the NetApiBufferAllocate function and other network management functions.
NetApiBufferReallocate | Changes the size of a buffer allocated by a call to the NetApiBufferAllocate function.
NetApiBufferSize | Returns the size, in bytes, of a buffer allocated by a call to the NetApiBufferAllocate function.

Windows NT/2000 or later: For remotable functions that return information to the caller, the RPC run-time library allocates the buffer containing the return information. When the caller has finished processing the information, it must call the NetApiBufferFree function to free the allocated buffer.


Audit Functions

Note The network management auditing functions are obsolete on Windows NT/Windows 2000 because the system uses an integrated event logging mechanism for reporting both audits and errors.

The network management auditing functions and error logging functions are provided to access LAN Manager 2.x logs. They will report ERROR_NOT_SUPPORTED if called on a Windows NT/Windows 2000 system.


Configuration Functions

Note The network management configuration functions are obsolete on Windows NT/Windows 2000. They are only for LAN Manager 2.x support. Use the registry functions to retrieve configuration information for Windows NT/Windows 2000 computers.


Directory Service Functions

The network management directory service functions allow developers to work with the domain controller and domain membership in the directory service.

The network management directory service functions are listed following.

Function | Description
NetGetJoinableOUs | Retrieves a list of organizational units (OUs) in which a computer account can be created.
NetGetJoinInformation | Retrieves join status information for the specified computer.
NetJoinDomain | Joins a computer to a workgroup or domain.
NetRenameMachineInDomain | Changes the name of a computer in a domain.
NetUnjoinDomain | Unjoins a computer from a workgroup or a domain.
NetValidateName | Verifies the validity of a computer name, workgroup name, or domain name.

For more information, see the Active Directory Reference.


Distributed File System (Dfs) Functions

The Distributed File System (Dfs) functions provide the ability to logically group shares on multiple servers and to transparently link shares into a single hierarchical name space. Dfs organizes shared resources on a network in a treelike structure.

Dfs supports stand-alone implementations of Dfs, those with one host server, and domain-based implementations that have multiple host servers and high availability. The Dfs topology data for domain-based implementations is stored in Active Directory. The data includes the Dfs root, Dfs links and a replica set.

Each Dfs tree structure has one or more root shares, which are stored on a physical server running the Dfs process. A root share can contain one or more Dfs links. Each Dfs link points to one or more shared folders on the network. You can add, modify and delete Dfs links from a Dfs root share. When you remove the last share associated with a Dfs link, Dfs deletes the Dfs link in the Dfs root share. (In earlier documentation, Dfs links were called junction points.)

When a Dfs link points to more than one shared folder, the folders are called replicas. When users access a Dfs link, the Dfs server selects one of the replicas based on site information, if it is available, and connects the user to the replica. This helps to distribute client requests across the replicas and can improve performance.

An application can use the Dfs functions to:

  • Add a Dfs link to a Dfs root.
  • Create or remove stand-alone and domain-based Dfs roots.
  • Add shares to an existing Dfs link.
  • Remove a Dfs link from a Dfs root.
  • Remove a Dfs path from a Dfs link.
  • View and configure information about the Dfs links in a named Dfs root.

The Dfs functions are listed following.

Function | Description
NetDfsAdd | Creates a new Dfs link or adds a share to an existing link.
NetDfsAddFtRoot | Creates a new domain-based Dfs root, or adds a new server and share to an existing domain-based Dfs implementation.
NetDfsAddStdRoot | Creates the root for a new stand-alone Dfs implementation.
NetDfsAddStdRootForced | Creates the root for a new stand-alone Dfs implementation in a cluster technology environment, allowing an offline share to host the Dfs root.
NetDfsEnum | Enumerates all Dfs links in a named Dfs root.
NetDfsGetClientInfo | Returns the client's cached information about a specific Dfs link.
NetDfsGetInfo | Returns information about a specific Dfs link.
NetDfsManagerInitialize | Reinitializes the Dfs service on a specified server.
NetDfsRemove | Removes a share from a Dfs link; removes the Dfs link if the share is the last associated with the specified link.
NetDfsRemoveFtRoot | Removes a server and share from a domain-based Dfs implementation; deletes the Dfs root if there are no more associated shares.
NetDfsRemoveFtRootForced | Removes the specified server from a domain-based Dfs implementation, even if the server is offline.
NetDfsRemoveStdRoot | Deletes the root of a stand-alone Dfs implementation.
NetDfsSetClientInfo | Modifies cached information about a Dfs link on a client computer.
NetDfsSetInfo | Associates information with a Dfs link.

Dfs functions are available at the following information levels:

DFS_INFO_1
DFS_INFO_2
DFS_INFO_3
DFS_INFO_4
DFS_INFO_100
DFS_INFO_101
DFS_INFO_102
DFS_INFO_200
DFS_STORAGE_INFO

Shares on computers that are running Windows NT Workstation, Windows 2000 Professional, Windows 95, Windows 98, or Windows for Workgroups can be published in a Dfs name space. You can also publish any non-Microsoft shares for which client redirectors are available in a Dfs name space. However, unlike a share that is published on a server that is running Windows NT Server 4.0 or Windows 2000 Server, they cannot host a Dfs share or point to other Dfs shares.

Dfs uses the Windows 2000 file replication service to copy changes between replicated shares. Users can modify files stored on one replica, and the file replication service propagates the changes to the other designated replicas. The service preserves the most recent change to a document or files.


Error Logging Functions

Note The network management error logging functions are obsolete on Windows NT/Windows 2000 because the system uses an integrated event logging mechanism for reporting both audits and errors.

The network management auditing functions and error logging functions are provided to access LAN Manager 2.x logs. They will report ERROR_NOT_SUPPORTED if called on a Windows NT/Windows 2000 system.


Get Functions

The network management get functions retrieve information about a domain. You can also call these functions to retrieve information about local, global, workstation, and server user accounts.

The network management get functions are listed following.

Function | Description
NetGetAnyDCName | Returns the name of any domain controller for a domain that is directly trusted by a specified server.
NetGetDCName | Returns the name of the primary domain controller (PDC) for the specified domain.
NetGetDisplayInformationIndex | Returns the index of the first display information entry whose name begins with a specified string or alphabetically follows the string.
NetQueryDisplayInformation | Returns user, computer, or global group account information.

The information returned by the NetQueryDisplayInformation function is available at the following levels:

NET_DISPLAY_GROUP
NET_DISPLAY_MACHINE
NET_DISPLAY_USER


Group Functions

A global group contains user accounts from one domain that are grouped together under one group account name. A global group can contain only members (users) from the domain where the global group is created; it cannot contain local groups or other global groups. A global group is available within its own domain and within any trusting domain.

The network management group functions control global groups. The group functions are listed following.

Function | Description
NetGroupAdd | Creates a global group.
NetGroupAddUser | Adds one user to an existing global group.
NetGroupDel | Removes a global group whether or not the group has any members.
NetGroupDelUser | Removes one user name from a global group.
NetGroupEnum | Lists all global groups on a server.
NetGroupGetInfo | Returns information about a particular global group.
NetGroupGetUsers | Lists all members of a particular global group.
NetGroupSetInfo | Sets general information about a global group.
NetGroupSetUsers | Assigns members to a new global group; replaces the members of an existing group.

When you call the NetGroupAdd function to create a global group, you must supply a group name. Initially, a new group has no members.

User accounts automatically belong to one of the special global groups Domain, Users, or None, according to the user's security requirements. Membership in these groups is indirectly controlled by the NetUserAdd, NetUserDel, and NetUserSetInfo functions.

Global group account information is available at the following levels:

GROUP_INFO_0
GROUP_INFO_1
GROUP_INFO_2
GROUP_INFO_3
GROUP_INFO_1002
GROUP_INFO_1005

The 1002 and 1005 levels are valid only for the NetGroupSetInfo function.

Global group member information is available at the following information level:

GROUP_USERS_INFO_0

For more information, see the network management Local Group Functions.

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 group functions. For more information, see IADsGroup.


Local Group Functions

A local group can contain user accounts or global group accounts from one or more domains. (Global groups can contain users from only one domain.) A local group shares common privileges and rights only within its own domain.

The network management local group functions control members of local groups in a way that the functions can only be called locally on the system on which the local group is defined. On a Windows NT/Windows 2000 workstation, or on a server that is not a domain controller, you can use only a local group defined on that system. A local group defined on the primary domain controller is replicated to all other domain controllers in the domain. Therefore, a local group is available on all domain controllers within the domain in which it was created.

The local group functions create or delete local groups, and review or adjust the memberships of local groups. These functions are listed following.

Function | Description
NetLocalGroupAdd | Creates a local group.
NetLocalGroupAddMembers | Adds one or more users or global groups to an existing local group.
NetLocalGroupDel | Deletes a local group, removing all existing members from the group.
NetLocalGroupDelMembers | Removes one or more members from an existing local group.
NetLocalGroupEnum | Returns information about each local group account on a server.
NetLocalGroupGetInfo | Returns information about a particular local group account on a server.
NetLocalGroupGetMembers | Lists all members of a specified local group.
NetLocalGroupSetInfo | Sets general information about a local group.
NetLocalGroupSetMembers | Assigns members to a local group.

You can add a member to a local group by specifying the security identifier (SID) of the member. To translate a member account name to a SID, call the LookupAccountName function.

When you create a local group by calling the NetLocalGroupAdd function, you must supply a local group name. Initially, the local group has no members.

Local group account information is available at the following levels:

LOCALGROUP_INFO_0
LOCALGROUP_INFO_1
LOCALGROUP_INFO_1002

Local group membership information is available at the following information levels:

LOCALGROUP_MEMBERS_INFO_0
LOCALGROUP_MEMBERS_INFO_1
LOCALGROUP_MEMBERS_INFO_2
LOCALGROUP_MEMBERS_INFO_3

You can retrieve the names of the local groups to which a user belongs by calling the NetUserGetLocalGroups function, specifying the following information level:

LOCALGROUP_USERS_INFO_0

For more information, see the network management Group Functions.

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 local group functions. For more information, see IADsGroup.


Message Functions

The network management message functions send messages and maintain message aliases. The message functions are listed following.

Function | Description
NetMessageBufferSend | Sends a message to a registered message alias.
NetMessageNameAdd | Registers a message alias in the message name table.
NetMessageNameDel | Deletes a message alias from the message name table.
NetMessageNameEnum | Lists all the message aliases stored in the message name table.
NetMessageNameGetInfo | Returns information about a particular message alias in the message name table.

A message is a buffer of text data sent to a user or application on the network. To receive a message, a user or application must register a message alias in a computer's table of message names. This can be done by calling the NetMessageNameAdd function. A message name table contains a list of registered message aliases (users and applications) permitted to receive messages. The aliases registered in the message name table are case insensitive.

The messenger service must be running on the receiving computer to display a pop-up message when the message is received. In addition, the Workstation service must be running on the local computer. Netbios is the transport mechanism used between the sender and receiver.

Message functions are available at two information levels:

MSG_INFO_0
MSG_INFO_1

MSG_INFO_1 exists only for compatibility. The messenger service does not forward names or allow names to be forwarded to it.


NetFile Functions

The network management file functions provide a way to monitor and close the file, device, and pipe resources open on a server. The file functions are listed following.

Function | Description
NetFileClose | Forces a resource to close.
NetFileEnum | Returns information about open files on a server.
NetFileGetInfo | Returns information about a particular opening of a server resource.

Call the NetFileClose function when the file cannot be closed by any other means. This function should be used with caution because NetFileClose does not write data cached on the client system to the file before closing the file.

The NetFileEnum function returns information about resources open on a server. A file can be opened one or more times by one or more applications. Each file opening is uniquely identified. The NetFileEnum function returns an entry for each file opening. The NetFileGetInfo function returns information about one opening of a resource.

File information is available at the following levels.

FILE_INFO_2
FILE_INFO_3

Levels 0 and 1 are not supported. Level 2 returns only the identification number assigned to the resource when it was opened. Level 3 returns the identification number, permissions, file locks, and the name of the user who opened the resource.

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 NetFileEnum and NetFileGetInfo functions. For more information, see IADsResource and IADsFileServiceOperations.

Windows 95/98/Me: The NetFileClose2 function forces a resource to close. This function can be used when an error prevents closure by any other means. The file_info_50 structure is supported on Windows 95 and Windows 98.


NetService Functions

Note The network management NetService functions are obsolete on Windows NT/Windows 2000 because the system provides a complete set of service functions. These should be used in place of the NetService functions, unless you need to control services on a LAN Manager 2.x server.

A service can be started using the service functions. At startup time, the service defines whether it can be stopped, paused, and continued. Windows NT/Windows 2000 networking provides several standard services, such as the workstation, server, and messenger services.


Remote Utility Functions

The network management remote utility functions are listed following.

Function | Description
NetRemoteComputerSupports | Queries the redirector to retrieve the optional features that a remote system supports.
NetRemoteTOD | Enables applications to access the time-of-day information on a remote server.

The remote time-of-day information is available at one information level:

TIME_OF_DAY_INFO


Replicator Functions

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

The Windows NT replicator service maintains identical sets of files and directories on different servers and workstations running Windows NT 4.0 or earlier. When you update files on one server, the file replicator service replaces the corresponding files on other servers and workstations with the updated files. The replication process simplifies the task of updating and coordinating files, and maintains the integrity of the replicated data. For more information about replication, see the following topics:

  • About export and import servers
  • About the file replicator service

Replication is controlled by options you set in the LANMAN.INI file using the following categories of network management replicator functions:

  • Replicator configuration functions
  • Replicator export directory functions
  • Replicator import directory functions

About Export and Import Servers

To replicate a set of files and directories on several computers, you must create a master set of files and directories on a server that you designate as an export server. Export servers maintain the master files in an export directory tree with a maximum of 32 levels. Each directory can contain as many as 1000 files.

Import servers are servers and workstations that receive replicated files. Import servers and workstations have import directories that correspond to the export directories. When a file changes in the export directory, the file replicator service copies the changes to the corresponding import directories on all designated import servers and workstations. The service replicates all directory and file additions and deletions to the import servers.

A network can have any number of export and import servers. A server can be designated as both an export and an import server. You can configure workstations only as import servers.

About the File Replicator Service

Before using the replicator functions, check the Control Panel Services application to make sure the file replicator service is configured to log on using a specific user account. The user account must be a member of the Replicator local group, the account must not be disabled, and the account must have permission to access the import and export trees on the respective servers.

Changing from file system replication control in LAN Manager 2.x to replicator function control in Windows NT has the following implications:

  • To terminate replication from a client's master, applications can no longer delete a directory in the client's import path.
  • To control the method of replication, applications can no longer use the REPL.INI file located in each replicated directory on the master.
  • To control replication of a master directory, applications can no longer create or delete USERLOCK.* files.
  • To prevent replication on a client from a master directory, applications can no longer create or delete USERLOCK.* files.
  • You will need to modify applications that depend on the LAN Manager 2.x behavior of ignoring locks for file integrity trees. (The Windows NT/Windows 2000 policy differs from LAN Manager 2.x policy; under Windows NT/Windows 2000 the locks are always respected.)

Each of the options listed preceding can be specified to the file replicator service by calling the appropriate network management replicator function.

Any user or application logged on as a member of either the administration group or the server operator group can modify the parameters that control the file replicator service. (This applies to both local and remote export servers.)

You can use the Windows NT file replicator service to copy relatively small directory trees. If you are attempting to replicate multimegabyte directory trees or trees containing thousands of directories and files, you should consider some other means of doing so.

Replicator Configuration Functions

You can use the replicator configuration functions to examine and modify the configuration parameters for the file replicator service. The replicator configuration functions are listed following.

Function | Description
NetReplGetInfo | Returns configuration information for the file replicator service.
NetReplSetInfo | Modifies configuration information for the file replicator service.

Configuration information for the file replicator service is available at the following levels:

REPL_INFO_0
REPL_INFO_1000
REPL_INFO_1001
REPL_INFO_1002
REPL_INFO_1003

Replicator Export Directory Functions

The replicator export directory functions control top-level directories under the export path on the master directory.

The replicator export directory functions are listed following.

Function | Description
NetReplExportDirAdd | Registers an existing directory in the export path for replication.
NetReplExportDirDel | Removes the registration of a replicated directory.
NetReplExportDirEnum | Lists the replicated directories in the export path.
NetReplExportDirGetInfo | Returns the control information for a replicated directory.
NetReplExportDirLock | Locks a directory so that replication of it can be suspended.
NetReplExportDirSetInfo | Modifies the control information for a replicated directory.
NetReplExportDirUnlock | Unlocks a directory so that replication of it can resume.

A master directory can be registered for replication in one of the following ways:

  • The file replicator service automatically registers a new directory for replication when a user creates it under the master directory's export path. In this case, the file replicator service gives the directory the REPL_INTEGRITY_FILE and REPL_EXTENT_TREE settings for the integrity and extent replication controls.
  • An application can call the NetReplExportDirAdd function to register a pre-existing directory in the export path for replication. When adding a directory in this manner, you must specify the settings for the integrity and extent replication controls using the rpedX_integrity and rpedX_extent members of the appropriate REPL_EDIR_INFO structure.

The integrity control determines when a master updates a client. The control can be one of the following values.

Value | Meaning
REPL_INTEGRITY_FILE | The client receives a replica of a file within the directory when the directory isn't being modified or replicated.
REPL_INTEGRITY_TREE | Before the file replicator service updates the client, each file and directory within the replicated directory must be stable for a specific period of time. This time is specified by the rp0_guardtime member of the REPL_INFO_0 structure. (Call the NetReplGetInfo function to retrieve this type of configuration information for the file replicator service.)

The extent control specifies the selection of files for replication within the main export directory. The control can be one of the following values.

Value | Meaning
REPL_EXTENT_TREE | The file replicator service replicates the entire tree within the directory.
REPL_EXTENT_FILE | The file replicator service replicates only the files in the first-level directory.

For additional information about these replication controls, see REPL_EDIR_INFO_1.

On systems running LAN Manager 2.x, the replication controls used to be specified in the REPL.INI file in each replicated directory. The controls could not be dynamically set. To examine the replication controls of a directory on Windows NT/Windows 2000, call the NetReplExportDirGetInfo function; to modify them, call NetReplExportDirSetInfo. Windows NT/Windows 2000 ignores the REPL.INI file.

You can call the replicator export directory functions whether or not the file replicator service is running. If the service is running on a master, modifications to the directory controls take effect immediately, and the changes persist after the file replicator service stops. If the service has not started, the changes to the directory controls are stored as persistent information and take effect when the file replicator service starts.

The replicator export directory functions are available at the following information levels:

REPL_EDIR_INFO_0
REPL_EDIR_INFO_1
REPL_EDIR_INFO_2
REPL_EDIR_INFO_1000
REPL_EDIR_INFO_1001

The rped2_lockcount and rped2_locktime members of the REPL_EDIR_INFO_2 structure contain lock status information.

Replicator Import Directory Functions

The replicator import directory functions designate the top-level directories in the client's import path that should receive updates from the master. The functions also return status information about a replicated directory on the client. (On LAN Manager 2.x, after a user creates a directory under the import path, the file replicator service automatically replicates to it.)

The replicator import directory functions are listed following.

Function | Description
NetReplImportDirAdd | Registers an existing directory in the import path to receive replication from a master.
NetReplImportDirDel | Removes the registration of a directory in the import path so that it no longer receives updates from the master; the function does not delete the directory from the file system.
NetReplImportDirEnum | Lists the client directories that are registered for replication.
NetReplImportDirGetInfo | Returns status information for a replicated directory on an import server.
NetReplImportDirLock | Locks a directory so that replication to it can be suspended.
NetReplImportDirUnlock | Unlocks a directory so that replication to it can resume.

You can register a client directory for replication in one of the following ways:

  • The file replicator service automatically adds a directory to the client's import path if the directory is exported by a master from which the import server is already importing.
  • An application can call the NetReplImportDirAdd function to register a preexisting directory in the import path for replication. This can be useful if you want to modify the import directory's properties prior to importing the directory; for example, you may want to lock the directory and suspend replication. (The function does not create the directory.)

You can call the replicator import directory functions whether or not the file replicator service is running. If the service is running on a client, directory additions and deletions take effect immediately, and the changes persist after the file replicator service stops. If the service has not started, and if there is a master that exports the directory, directory additions receive updates when the file replicator service starts.

The replicator import directory functions are available at the following information levels:

REPL_IDIR_INFO_0
REPL_IDIR_INFO_1


Schedule Functions

The network management schedule service functions submit and manage jobs that execute on a specified computer at a particular time (or times) in the future. Jobs can include commands and programs. The functions manage jobs at remote and local computers, provided the schedule service is running on the computer.

The schedule service functions are listed following.

Function | Description
NetScheduleJobAdd | Submits a job to run at a specified future date and time.
NetScheduleJobDel | Cancels a range of jobs queued to run on a computer.
NetScheduleJobEnum | Lists the jobs queued on a specified computer.
NetScheduleJobGetInfo | Returns information about a particular job queued on a computer.

For the network management schedule functions to succeed, a caller must have administrator's privilege at a computer where the schedule service is running. The schedule service functions are also known as "Job" and "AT command" functions.

The AT_INFO structure is used by the NetScheduleJobAdd function to specify information when submitting a job, and by the NetScheduleJobGetInfo function to retrieve information about a job that has been submitted. The AT_ENUM structure is used by NetScheduleJobEnum to enumerate and return information about an entire queue of submitted jobs.


Server Functions

The network management server functions perform administrative tasks on a local or remote server. The server functions are listed following.

Function | Description
NetServerDiskEnum | Returns a list of local disk drives on a server.
NetServerEnum | Lists all visible servers of a particular type (or types) in the specified domain.
NetServerGetInfo | Returns configuration information about a specified server.
NetServerSetInfo | Sets the operating parameters for a server.

Any user or application with admin group membership on a local or remote server can perform administrative tasks on that server to control the server's operation, user access, and resource sharing. The low-level parameters that affect a server's operation can be examined and modified by calling the NetServerGetInfo and NetServerSetInfo functions. These parameters are defined in the server's LANMAN.INI file.

Most network management server functions execute only on a remote server. The NetServerEnum function executes on either a local workstation or a remote server. If you attempt to execute other server functions on a local workstation, the functions return the error NERR_RemoteOnly.

Server-specific information is available at the following levels, starting at level 100:

SERVER_INFO_100
SERVER_INFO_101
SERVER_INFO_102
SERVER_INFO_402
SERVER_INFO_403
SERVER_INFO_1501
SERVER_INFO_1502
SERVER_INFO_1503
SERVER_INFO_1506
SERVER_INFO_1509
SERVER_INFO_1510
SERVER_INFO_1511
SERVER_INFO_1512
SERVER_INFO_1513
SERVER_INFO_1515
SERVER_INFO_1516
SERVER_INFO_1518
SERVER_INFO_1523
SERVER_INFO_1528
SERVER_INFO_1529
SERVER_INFO_1530
SERVER_INFO_1533
SERVER_INFO_1536
SERVER_INFO_1538
SERVER_INFO_1539
SERVER_INFO_1540
SERVER_INFO_1541
SERVER_INFO_1542
SERVER_INFO_1544
SERVER_INFO_1550
SERVER_INFO_1552

The server information levels that were available in LAN Manager 2.x are no longer available. However, the following structures are supported on LAN Manager 2.x systems:

SERVER_INFO_1005
SERVER_INFO_1010
SERVER_INFO_1016
SERVER_INFO_1017
SERVER_INFO_1018
SERVER_INFO_1107

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 server functions. For more information, see IADsComputer.

Windows 95/98/Me: The following information levels are supported on Windows 95 and Windows 98:

server_info_1
server_info_50

For more information, see the Server and Workstation Transport Functions.


Server and Workstation Transport Functions

The network management server and workstation transport functions handle binding and unbinding of transport protocols to and from the server and redirector. The server transport functions deal with transport protocols managed by the server; on Windows NT 4.0 and earlier, the workstation transport functions deal with transport protocols managed by the redirector.

File sharing between a transport device and a server has two components:

  • The server computer where the files reside
  • A Server Message Block (SMB) client that accesses the files

The client computer communicates with the server computer over a local area network using a transport protocol; for example, TCP or XNS. The client sends requests to the server to retrieve data. The software on the client computer that generates the file requests is called the redirector because it redirects local file requests to the server computer. The software on the computer that receives and acts on the file requests is called the server because it serves the clients. The format specific to these requests is called the SMB protocol.

The server transport functions are listed following.

Function | Description
NetServerComputerNameAdd | Binds an emulated server name to each of the transport protocols on which a server is active. (Combines the functionality of the NetServerTransportEnum function and the NetServerTransportAddEx function.)
NetServerComputerNameDel | Disconnects each network transport protocol from an emulated server name set by a previous call to the NetServerComputerNameAdd function.
NetServerTransportAdd | Binds the specified server to the transport protocol. (This function supports only the SERVER_TRANSPORT_INFO_0 information level.)
NetServerTransportAddEx | Binds the specified server to the transport protocol. (This extended function supports the SERVER_TRANSPORT_INFO_1, SERVER_TRANSPORT_INFO_2, and SERVER_TRANSPORT_INFO_3 information levels.)
NetServerTransportDel | Disconnects the transport protocol from the server.
NetServerTransportEnum | Enumerates the transport protocols managed by the server.

Server transport functions are available at the following information levels:

SERVER_TRANSPORT_INFO_0
SERVER_TRANSPORT_INFO_1
SERVER_TRANSPORT_INFO_2
SERVER_TRANSPORT_INFO_3

The workstation transport functions perform equivalent operations for the workstation.

Windows 2000 or later: The Windows 2000 redirector does not support the NetWkstaTransportAdd function or the NetWkstaTransportDel function. You can change the default settings for transport protocols manually through the Local Area Connection Properties dialog box in the Network and Dial-Up Connections folder.

The workstation transport functions are listed following.

Function | Description
NetWkstaTransportAdd | Connects the redirector to the transport protocol.
NetWkstaTransportDel | Disconnects the transport protocol from the redirector.
NetWkstaTransportEnum | Lists the transport protocols that are managed by the redirector.

Workstation transport functions are available at one information level:

WKSTA_TRANSPORT_INFO_0


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 five information levels:

SESSION_INFO_0
SESSION_INFO_1
SESSION_INFO_2
SESSION_INFO_10
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. For more information, see IADsSession and IADsFileServiceOperations.

Windows 95/98/Me: The following information levels are supported on Windows 95 and Windows 98:

session_info_0
session_info_1
session_info_2
session_info_10
session_info_50


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.

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.

The network management functions use the following special share names for interprocess communication (IPC) and remote administration of the server:

  • IPC$, reserved for interprocess communication
  • ADMIN$, reserved for remote administration
  • 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:

SHARE_INFO_0
SHARE_INFO_1
SHARE_INFO_2
SHARE_INFO_501
SHARE_INFO_502
SHARE_INFO_1005

The following information levels are valid only for NetShareSetInfo:

SHARE_INFO_1004
SHARE_INFO_1006

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. For more information, see IADsFileShare.

Windows 2000 or later: The SHARE_INFO_1501 information level is supported only on Windows 2000.

Windows 95/98/Me: The following information levels are supported on Windows 95 and Windows 98:

connection_info_50
share_info_1
share_info_50


Statistics Functions

Windows NT/Windows 2000 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.

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:

USE_INFO_0
USE_INFO_1
USE_INFO_2

Information level 2 is not available if the function is accessed with a LAN Manager 2.x system. In that case, the function returns ERROR_NOT_SUPPORTED.


User Functions

The network management user functions control a user's account in the security database. 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 Windows NT/Windows 2000 Server 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 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:

USER_INFO_0
USER_INFO_1
USER_INFO_2
USER_INFO_3
USER_INFO_4
USER_INFO_10
USER_INFO_11
USER_INFO_20
USER_INFO_21
USER_INFO_22
USER_INFO_23

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

USER_INFO_1003
USER_INFO_1005
USER_INFO_1006
USER_INFO_1007
USER_INFO_1008
USER_INFO_1009
USER_INFO_1010
USER_INFO_1011
USER_INFO_1012
USER_INFO_1014
USER_INFO_1017
USER_INFO_1020
USER_INFO_1024
USER_INFO_1051
USER_INFO_1052
USER_INFO_1053

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. For more information, see IADsUser and IADsComputer.


User Modal Functions

The network management user modal functions control the system-wide parameters that affect the Windows NT/Windows 2000 security system behavior.

The user modal functions are listed following.

Function | Description
NetUserModalsGet | Returns global information for all users and global groups in the security database.
NetUserModalsSet | Sets global information for all users and global groups in the security database.

The NetUserModalsGet and NetUserModalsSet functions examine and modify the modal settings, which are global parameters that affect every account in the security database (for example, the minimum allowable password length). All modal settings can be altered by calling NetUserModalsSet. Most of the modals can also be altered by using the net accounts command. The network management user modal functions do not require the server to have user-level security.

User modal information is available at the following levels:

USER_MODALS_INFO_0
USER_MODALS_INFO_1
USER_MODALS_INFO_2
USER_MODALS_INFO_3

The following information levels are valid only for NetUserModalsSet and replace the older way of passing in a Parmnum to set a specific field:

USER_MODALS_INFO_1001
USER_MODALS_INFO_1002
USER_MODALS_INFO_1003
USER_MODALS_INFO_1004
USER_MODALS_INFO_1005
USER_MODALS_INFO_1006
USER_MODALS_INFO_1007

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 modal functions. For more information, see IADsDomain.


Workstation and Workstation User Functions

The network management workstation functions perform administrative tasks on a local or remote workstation. Any user or application with admin group membership, on a local or remote server, can perform administrative tasks on a workstation to control its operation, user access, and resource sharing.

The workstation functions are listed following.

Function | Description
NetWkstaGetInfo | Returns information about the configuration elements for a workstation.
NetWkstaSetInfo | Configures a workstation.

The workstation functions allow access to two discrete types of workstation information:

  • System information
  • Platform-specific information (Windows NT, OS/2, MS-DOS, and so on)

Within each type the data is categorized by security access. Data that is guest-accessible is a subset of the data that is user-accessible, which is in turn a subset of the admin-accessible data.

The workstation information structures have been restructured from those of LAN Manager 2.x to allow the information to be grouped by type and security accesses. The LAN Manager 2.x workstation information format has been discontinued due to the following:

  • The base levels (0 and 1) were not grouped by accessibility. A non-superset level (level 10) was required to allow guest access to the information.
  • Platform-specific implementation information was included in the base levels such that every platform had to return all information including a default for non-relevant fields. This increased the size of the information structures unnecessarily, making the functions cumbersome to use.

Workstation information is available at the following levels:

WKSTA_INFO_100
WKSTA_INFO_101
WKSTA_INFO_102

The network management workstation user functions allow access to user-specific information. The user-specific information is separated from the workstation information because there can be more than one user on a workstation.

The workstation user functions are listed following.

Function | Description
NetWkstaUserEnum | Lists information about all users currently logged on to the workstation.
NetWkstaUserGetInfo | Returns information about one currently logged-on user.
NetWkstaUserSetInfo | Sets the user-specific information for the configuration elements of a workstation.

Workstation user information is available at the following levels:

WKSTA_USER_INFO_0
WKSTA_USER_INFO_1
WKSTA_USER_INFO_1101


Security Requirements for the Network Management Functions

Calling some of the network management functions does not require special group membership. Other functions require that users have a specific privilege level to execute successfully. When applicable, the Security Requirements section on a function's reference page indicates the privilege level a user must have to execute the particular function.

The security requirements that apply when you make calls to certain network management functions on Windows 2000 are different than the requirements that apply when you call the functions on Windows NT. The functions include, among others, all those that begin with NetGroup, NetLocalGroup, and NetUser. For a complete list of affected functions, see the end of this topic. For requirements that apply to an individual network management function, please see the function's reference page.

Windows 2000 Active Directory domain controllers: If you call one of the affected functions on a Windows 2000 domain controller running Active Directory™, access to a securable object is allowed or denied based on the access-control list (ACL) for the object. (ACLs are specified in the directory.)

For queries, the default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view information. For updates, the default ACL permits only Administrators and account operators to write information.

Note By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access (Anonymous Logon) to information if the system allows anonymous access. Administrators can remove Everyone from the "Pre-Windows 2000 Compatible Access" group when installing a domain controller. Removing Everyone from the group restricts information access to authenticated users only.

Anonymous access to securable objects can also be restricted by setting the following key in the registry to the value 1. (This is also referred to as the RestrictAnonymous policy setting.)

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\RestrictAnonymous

Windows 2000 servers and workstations: If you call one of the affected functions on a Windows 2000 member server or workstation to perform a query, all authenticated users can view the information. Anonymous access is also possible if the RestrictAnonymous policy setting allows anonymous access. For updates, only Administrators and account operators can write information.

The preceding security requirements apply to the following network management query functions when you call them on Windows 2000:

NetGroupEnum
NetGroupGetInfo
NetGroupGetUsers

NetLocalGroupEnum
NetLocalGroupGetInfo
NetLocalGroupGetMembers

NetQueryDisplayInformation

NetSessionGetInfo (levels 1 and 2 only)

NetShareEnum (level 2 only)

NetUserEnum
NetUserGetGroups
NetUserGetInfo
NetUserGetLocalGroups
NetUserModalsGet

NetWkstaGetInfo
NetWkstaUserEnum

The security requirements also apply to the following network management update functions on Windows 2000:

NetGroupAdd
NetGroupAddUser
NetGroupDel
NetGroupDelUser
NetGroupSetInfo
NetGroupSetUsers

NetLocalGroupAdd
NetLocalGroupAddMembers
NetLocalGroupDel
NetLocalGroupDelMembers
NetLocalGroupSetInfo
NetLocalGroupSetMembers

NetMessageBufferSend

NetUserAdd
NetUserChangePassword
NetUserDel
NetUserModalsSet
NetUserSetGroups
NetUserSetInfo

For more information about the Windows NT/Windows 2000 security model for controlling access to securable objects, see Access Control.


Mapping ADSI Interfaces to the Network Management Functions

The Active Directory™ Service Interfaces (ADSI) are a set of COM interfaces used to access the capabilities of directory services from different network providers. ADSI presents a single set of directory service interfaces for managing network resources in a distributed computing environment.

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

The following table lists network management functions and function groups, and the ADSI interfaces to which the functions map.

Functions | Interfaces
NetFileEnum, NetFileGetInfo | IADsResource, IADsFileServiceOperations
NetGroup* | IADsGroup
NetLocalGroup* | IADsGroup
NetServer* | IADsComputer
NetSession* | IADsSession, IADsFileServiceOperations
NetShare* | IADsFileShare
NetUser* | IADsUser, IADsComputer
NetUserModals* | IADsDomain

For more information about directory services and programming with ADSI, see Active Directory, ADSI, and Directory Services. For information about the custom properties the WinNT provider makes available for the User class, and the property methods of the IADsUser interface the WinNT provider does not support, see ADSI WinNT Provider.


Network Management Data

The following topics discuss the data buffers, alignment, structures, and handles used by the network management functions.

  • Network Management Function Buffers
  • Network Management Function Buffer Lengths
  • API Data Alignment
  • Embedded Strings
  • Enumeration Resume Handles
  • Function Status
  • NLS Support
  • Parameter Error Reporting
  • RPC Buffer Allocation Errors
  • Obsolete Information Fields


Network Management Function Buffers

Windows NT/2000 or later: The RPC run-time library handles the buffers required by the 32-bit data retrieval network management functions as follows:

  • Sending data to the server (data specified by [in] parameters).

    The caller must allocate the buffer for the relevant information structure (or structures) and pass a pointer variable to the function. The caller does not need to specify the buffer length.

    Example: NetGroupAdd

  • Retrieving data from the server (data specified by [out] parameters).

    The system allocates the buffer for the returned information. The caller must pass a pointer variable to the function on input. On successful return, the pointer receives the address of the system-allocated buffer that contains the returned information. This simplifies the calling code, because the caller does not need to estimate the size of the buffer, or resize the buffer and reissue the function.

    When the caller has finished processing the returned information, it must free the system-allocated memory by calling the NetApiBufferFree function. For more information about specifying buffer sizes, see Network Management Function Buffer Lengths.

    Example: NetGroupEnum

Windows 95/98/Me: The caller must provide and free all buffers required by the network management functions.


Network Management Function Buffer Lengths

Applications that specify buffer sizes when calling network management enumeration functions (and various data retrieval functions) must specify buffers large enough to hold the returned information structure (or structures) plus the strings to which their members point. If you do not specify a large enough buffer to receive all the available entries, the function returns ERROR_MORE_DATA. Enumeration calls do not return partial entries.

Windows NT/2000 or later: The network management functions take an advisory maximum data-length parameter, prefmaxlen. This parameter allows an application to suggest the number of bytes the server should return from a function call.

If you specify the value MAX_PREFERRED_LENGTH in the prefmaxlen parameter, the network management functions allocate the amount of memory required for the data.

Windows 95/98/Me: The caller must provide and free all buffers required by the network management functions.

For more information, see Network Management Function Buffers.


API Data Alignment

All structures specified for the network management functions must be 32-bit word aligned. The base size for a structure element is a DWORD.


Embedded Strings

Information structures will not contain embedded strings. This improves the alignment of the information structures and allows for OEM flexibility in the core functions.

Any information field that is returned in an enumeration call that can be subsequently used as a key for a GetInfo call is guaranteed to be present in the enumeration buffer. If the variable-length information string that would specify the key field value will not fit, then the entire fixed-length structure for the entry is not returned. Other variable-length fields will be returned as a NULL pointer for the case in which the string does not fit.


Enumeration Resume Handles

Enumeration resume handles are identifiers for the actual resume key contained in the instance data for the function. This is required for security, interoperability, and to simplify the caller code for the function.

If a NULL is passed for the pointer to the resume handle, no handle is stored and the enumeration search cannot be continued. This is useful in cases where the application does not want to enumerate all the items.

If an error is returned from an enumeration call, the resume handle must be treated as invalid and not used for any subsequent enumeration calls. When this occurs you must restart the enumeration from the beginning.


Function Status

The network management functions return zero on success; a nonzero return code indicates an error. Because the network management functions use RPC, the error definitions include RPC error codes. For more information, see Network Management Error Codes.


NLS Support

Windows NT/2000 or later: The network management functions take Unicode strings as input and provide Unicode strings on output. If your application generally works with ANSI strings, care must be taken to convert to and from Unicode where appropriate.

Windows 95/98/Me: Because the system does not support Unicode, the network management functions require ANSI strings.


Parameter Error Reporting

The Add and SetInfo functions return an index for a parameter in error. The caller may pass a NULL pointer for the parm_err parameter indicating that the field should not be set by the function. For functions that are accessed through LAN Manager 2.x servers, this field is returned as PARM_ERROR_UNKNOWN.


RPC Buffer Allocation Errors

Because the RPC run-time library allocates memory for send and receive buffers, the function should expect RPC allocation errors. In the event of an RPC allocation error, a resumable handle is invalidated. This is a requirement because resumable functions are not rewindable.


Obsolete Information Fields

Many of the information fields in the core information structures will be obsolete. These fields will remain in the information structure for compatibility with 16-bit versions of Windows and will return an intelligent default on 32-bit Windows systems.


Platform Support

The network management functions are implemented on all Win32 platforms. However, there are implementation differences between the platforms. The following sections contain platform-specific information.

  • Windows 95/98 support
  • Functions that only have support for remoting to LAN Manager 2.x
  • Requests from 16-bit LAN Manager clients
  • Calling 16-bit LAN Manager servers


Windows 95/98 Support

The following 32-bit network management functions are supported by Windows 95 and Windows 98:

  • NetAccessAdd
  • NetAccessCheck
  • NetAccessDel
  • NetAccessEnum
  • NetAccessGetInfo
  • NetAccessGetUserPerms
  • NetAccessSetInfo
  • NetConnectionEnum
  • NetFileClose2
  • NetFileEnum
  • NetSecurityGetInfo
  • NetServerGetInfo
  • NetSessionDel
  • NetSessionEnum
  • NetSessionGetInfo
  • NetShareAdd
  • NetShareDel
  • NetShareEnum
  • NetShareGetInfo
  • NetShareSetInfo

You can also thunk to the 16-bit LAN Manager functions on Windows 95/98. For information on these functions, please see the 16-bit LanMan Programmer's Toolkit. This toolkit is available through the Microsoft Developer Network (MSDN). For information on thunking, see Thunk Compiler.

In addition, the following network management structures are supported by Windows 95 and Windows 98.

connection_info_50
file_info_50
security_info_1
server_info_1
server_info_50
session_info_0
session_info_1
session_info_2
session_info_10
session_info_50
share_info_1
share_info_50

For more information, see Windows 95/98 network management code samples.


Functions That Only Have Support for Remoting to LAN Manager 2.x

On Windows NT/Windows 2000, the following functions are supported only for remoting to a LAN Manager 2.x computer.

  • NetAccessAdd
  • NetAccessCheck
  • NetAccessDel
  • NetAccessEnum
  • NetAccessGetUserPerms
  • NetAccessSetInfo
  • NetAuditClear
  • NetAuditRead
  • NetAuditWrite
  • NetConfigGet
  • NetConfigGetAll
  • NetConfigSet
  • NetErrorLogClear
  • NetErrorLogRead
  • NetErrorLogWrite

For information on these functions, please see the 16-bit LanMan Programmer's Toolkit. This toolkit is available through the Microsoft Developer Network (MSDN).


Requests from 16-bit LAN Manager Clients

Windows NT/Windows 2000 provides support for most remote functions called from LAN Manager 2.x clients. However, the following function calls are not supported when they are accessed with a LAN Manager 2.x client to a Windows NT/Windows 2000 server:

  • DosPrintDriverEnum
  • DosPrintQProcessorEnum
  • DosPrintPortEnum
  • DosPrintDest
  • NetAccessCheck
  • NetAlertRaise
  • NetAlertStart
  • NetAlertStop
  • NetAuditClear
  • NetAuditOpen
  • NetAuditRead
  • NetAuditWrite
  • NetConfigGet2
  • NetConfigGetAll2
  • NetConfigSet
  • NetErrorLogOpen
  • NetErrorLogClear
  • NetFileClose
  • NetFileEnum
  • NetFileGetInfo
  • NetHandleGetInfo
  • NetHandleSetInfo
  • NetMessageFileSend
  • NetMessageLogFileSet
  • NetMessageLogFileGet
  • NetMessageNameFwd
  • NetMessageNameUnFwd
  • NetNetBiosEnum
  • NetNetBiosGetInfo
  • NetProfileSave
  • NetProfileLoad
  • NetServerAdminCommand
  • NetServerEnum
  • NetServiceStatus
  • NetStatisticsGet
  • NetStatisticsClear
  • NetUseAdd
  • NetUseDel
  • NetUseEnum
  • NetUseGetInfo
  • NetUserAdd
  • NetUserSetInfo
  • NetUserValidate2
  • NetWkstaSetUID

For information on these functions, please see the 16-bit LanMan Programmer's Toolkit. This toolkit is available through the Microsoft Developer Network (MSDN).


Calling 16-bit LAN Manager Servers

When an RPC-based function fails to connect to the appropriate interface, the client-side stub may attempt to initiate a function request to activate the selected server. For most of the Win32 networking functions specified in this document, and any API where the functionality and data formats are changed only for 32-bit usage, the conversion is straightforward. For components that offer new functionality the caller of the function should generally be aware of the destination type. When the new function offers a superset of the functionality of the LAN Manager 2.x station the same function is used for both destinations, but the new function members must have either a reserved value of an associated field to inform the conversion layer the field may be ignored if going LAN Manager 2.x systems. This is required so that a function caller is not misled as to the action performed when the function was called.


Using Network Management

This section discusses how to use the network management functions in your application.

  • Looking up a user's full name
  • Forcing a user to change the logon password
  • Changing elements of user information
  • Creating a new computer account
  • Creating a local group and adding a user
  • Determining the validating server on Windows 95/98
  • Looking up text for error code numbers

This section also provides code samples demonstrating use of the 32-bit network management functions that are supported by Windows 95 and Windows 98. (You can find code samples demonstrating the network management functions supported by Windows NT/Windows 2000 on the appropriate reference page.)

  • Windows 95/98 network management code samples


Looking Up a User's Full Name

Computers running Windows NT/Windows 2000 can be organized into a domain, which is a collection of computers on a Windows NT Server/Windows 2000 Server network. The domain administrator maintains centralized user and group account information.

To find the full name of a user, given the user name and domain name:

  • Convert the user name and domain name to Unicode, if they are not already Unicode strings.
  • Look up the computer name of the domain controller (DC) by calling NetGetDCName.
  • Look up the user name on the DC computer by calling NetUserGetInfo.
  • Convert the full user name to ANSI, unless the program is expecting to work with Unicode strings.

The following sample code is a function (GetFullName) that takes a user name and a domain name in the first two arguments and returns the user's full name in the third argument.

#include <windows.h>
#include <lm.h>
#include <stdio.h>

BOOL GetFullName( char *UserName, char *Domain, char *dest )
{
    WCHAR wszUserName[256];          // Unicode user name
    WCHAR wszDomain[256];
    LPBYTE ComputerName;

    struct _SERVER_INFO_100 *si100;  // Server structure
    struct _USER_INFO_2 *ui;         // User structure

// Convert ANSI user name and domain to Unicode

    MultiByteToWideChar( CP_ACP, 0, UserName,
        strlen(UserName)+1, wszUserName,
     sizeof(wszUserName)/sizeof(wszUserName[0]) );
    MultiByteTOWideChar( CP_ACP, 0, Domain,
        strlen(Domain)+1, wszDomain, sizeof(wszDomain)/sizeof(wszDomain[0]) );

// Get the computer name of a DC for the domain.

    NetGetDCName( NULL, wszDomain, &ComputerName );

// Look up the user on the DC.

    if( NetUserGetInfo( (LPWSTR) ComputerName,
        (LPWSTR) &wszUserName, 2, (LPBYTE *) &ui ) )
    {
        printf( "Error getting user information.\n" );
        return( FALSE );
    }

// Convert the Unicode full name to ANSI.

    WideCharToMultiByte( CP_ACP, 0, ui->usri2_full_name, -1,
        dest, 256, NULL, NULL );

    return (TRUE);
}


Forcing a User to Change the Logon Password

This code sample demonstrates how to force a user to change the logon password on the next logon using the NetUserGetInfo and NetUserSetInfo functions and the USER_INFO_3 structure.

Set the usri3_password_expired member of the USER_INFO_3 structure to a nonzero value using the following code fragment:

#define UNICODE
#include <windows.h>
#define INCL_NET
#include <stdio.h>
#include <lm.h>

#define USERNAME TEXT("your_user_name")
#define SERVER TEXT("\\\\server")

void main( void )
{
         PUSER_INFO_3 pUsr = NULL;
         NET_API_STATUS netRet = 0;
         DWORD dwParmError = 0;
//
// First, retrieve the user information at level 3. This is
//  necessary to prevent resetting other user information when
//  the NetUserSetInfo call is made.
//
netRet = NetUserGetInfo( SERVER, USERNAME, 3, (LPBYTE *)&pUsr);
 if( netRet == NERR_Success )
 {
//
// The function was successful;
//  set the usri3_password_expired value to a nonzero value.
//  Call the NetUserSetInfo function.
//
pUsr->usri3_password_expired = TRUE;
netRet = NetUserSetInfo( SERVER, USERNAME, 3, (LPBYTE)pUsr, &dwParmError);
//
// A zero return indicates success.
// If the return value is ERROR_INVALID_PARAMETER,
//  the dwParmError parameter will contain a value indicating the
//  invalid parameter within the user_info_3 structure. These values
//  are defined in the lmaccess.h file.
//
if( netRet == NERR_Success )
     printf("User %S will need to change password at next logon", USERNAME);
else printf("Error %d occurred.  Parm Error %d returned.\n", netRet, dwParmError);
//
// Must free the buffer returned by NetUserGetInfo.
//
NetApiBufferFree( pUsr);
}
else
printf("NetUserGetInfo failed: %d\n",netRet);
}


Changing Elements of User Information

The network management functions provide a variety of information levels to assist in changing user information. Some levels require administrative privileges to execute successfully.

The sample code in this topic demonstrates how to change several elements of user information by calling the NetUserSetInfo function. The code uses various network management information structures.

When changing user information, it is best to use the specific level for that piece of information. This prevents the accidental resetting of unrelated information when using the lower level values.

Setting some of the more commonly used levels is illustrated in the following code samples:

  • Setting the User Password, Level 1003
  • Setting the User Privilege, Level 1005
  • Setting the User Home Directory, Level 1006
  • Setting the User Comment Field, Level 1007
  • Setting the User Flags, Level 1008
  • Setting the User Script Path, Level 1009
  • Setting The User Authority Flags, Level 1010
  • Setting The User Full Name, Level 1011

All code fragments assume that the user has defined the UNICODE compile directive and included the appropriate SDK header files, as follows:

#define UNICODE
#include <windows.h>
#define INCL_NET
#include <lm.h>

Setting the User Password, Level 1003

The following code fragment illustrates how to set a user's password to a known value with a call to the NetUserSetInfo function. The USER_INFO_1003 topic contains additional information.

#define PASSWORD TEXT("new_password")

.
.
.
USER_INFO_1003 usriSetPassword;
DWORD netRet = 0;
//
// Set the usri1003_password member to point to a Unicode string.
//
// SERVER and USERNAME can be hard-coded TEXT("") strings
//  or pointers to Unicode strings.
//
usriSetPassword.usri1003_password  = PASSWORD;
netRet = NetUserSetInfo( SERVER, USERNAME,  1003, (LPBYTE)&usriSetPassword);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Privilege, Level 1005

The following code fragment illustrates how to specify the level of privilege assigned to a user with a call to the NetUserSetInfo function. The USER_INFO_1005 topic contains additional information.

USER_INFO_1005 usriPriv;
DWORD netRet = 0;
//
// Set the usri1005_priv member to the appropriate value;
//  then call NetUserSetInfo.
//
// SERVER and USERNAME can be hard-coded TEXT("") strings
//  or pointers to Unicode strings.
//
usriPriv.usri1005_priv  = USER_PRIV_USER;
netRet = NetUserSetInfo( SERVER, USERNAME,  1005, (LPBYTE)&usriPriv);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Home Directory, Level 1006

The following code fragment illustrates how to specify the path of a user's home directory with a call to the NetUserSetInfo function. The directory can be a hard-coded path or a valid Unicode path. The USER_INFO_1006 topic contains additional information.

#define HOMEDIR TEXT("C:\\USER\USER_PATH")
USER_INFO_1006 usriHomeDir;
//
// Set the usri1006_home_dir member to point to a valid Unicode string
//  for the new home directory.
//
// SERVER and USERNAME can be hard-coded TEXT("") strings
//  or pointers to Unicode strings.
//
usriHomeDir.usri1006_home_dir  = HOMEDIR;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriHomeDir);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Comment Field, Level 1007

The following code fragment illustrates how to associate a comment with a user by calling the NetUserSetInfo function. The USER_INFO_1007 topic contains additional information.

#define COMMENT TEXT("This is my Comment Text for the user")
USER_INFO_1007 usriComment;
//
// Set the usri1007_comment member to point to
//  a valid Unicode comment string.
//
// SERVER and USERNAME can be hard-coded TEXT("") strings
//  or pointers to Unicode strings.
//
usriComment.usri1007_comment  = COMMENT;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriComment);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Flags, Level 1008

The following code fragment illustrates how to set user flags with a call to the NetUserSetInfo function. The USER_INFO_1008 topic contains a list of valid values for the flags and a description of each flag.

Note that the UF_SCRIPT flag must be set for Windows NT/Windows 2000 and LAN Manager networks. Trying to set other flags without setting UF_SCRIPT on a Windows NT/Windows 2000 or LAN Manager network will cause the NetUserSetInfo function to fail.

#define USR_FLAGS UF_SCRIPT | UF_NORMAL_ACCOUNT
USER_INFO_1008 usriFlags;
//
// Set the usri1008_flags member to the appropriate constant.
//
// SERVER and USERNAME can be hard-coded TEXT("") strings
//  or pointers to Unicode strings.
//
usriFlags.usri1008_flags  = USR_FLAGS;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriFlags);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting the User Script Path, Level 1009

The following code fragment illustrates how to set the path for the logon script file of a particular user with a call to the NetUserSetInfo function. The script file can be a .CMD file, an .EXE file, or a .BAT file. The string can also be null. The USER_INFO_1009 topic contains additional information.

#define SCRIPT_PATH "C:\\BIN\\MYSCRIPT.BAT"
USER_INFO_1009 usriScrPath;
//
// Set the usri1009_script_path member to a Unicode
//  string constant or a pointer to a Unicode string.
//
// SERVER and USERNAME can be hard-coded TEXT("") strings
//  or pointers to Unicode strings.
//
usriScrPath.usri1009_script_path  = SCRIPT_PATH;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriScrPath);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting The User Authority Flags, Level 1010

The following code fragment illustrates how to set the operator privilege flags for a user with a call to the NetUserSetInfo function. The USER_INFO_1010 topic contains a list of valid values for the flags and a description of each flag.

#define AUTHORITY_FLAGS AF_OP_ACCOUNTS
USER_INFO_1010 usriAuthFlags;
//
// Set the usri1010_auth_flags member to a constant
//  containing the appropriate flag values.
//
// SERVER and USERNAME can be hard-coded TEXT("") strings
//  or pointers to Unicode strings.
//
usriAuthFlags.usri1010_auth_flags  = SCRIPT_PATH;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriAuthFlags);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);

Setting The User Full Name, Level 1011

The following code fragment illustrates how to set a user's full name with a call to the NetUserSetInfo function. The USER_INFO_1011 topic contains additional information.

#define USER_FULL_NAME TEXT("Joe B. User")
USER_INFO_1011 usriFullName;
//
// Set the usri1011_full_name member to a Unicode
//  string constant or a pointer to a Unicode string.
//
// SERVER and USERNAME can be hard-coded TEXT("") strings
//  or pointers to Unicode strings.
//
usriFullName.usri1011_full_name  = USER_FULL_NAME;
netRet = NetUserSetInfo( SERVER, USERNAME,  1006, (LPBYTE)&usriFullName);
if( netRet == NERR_Success ) printf("Success!\n");
else printf( "ERROR: %d Returned from NetUserSetInfo\n", netRet);


Creating a New Computer Account

The following code sample demonstrates how to create a new computer account using the NetUserAdd function.

The following are considerations for managing computer accounts:

  • The computer account name should be all uppercase for consistency with Windows NT/Windows 2000 account management utilities.
  • A computer account name always has a trailing dollar sign ($). Any functions used to manage computer accounts must build the computer name such that the last character of the computer account name is a dollar sign ($). For interdomain trust, the account name is TrustingDomainName$.
  • The maximum computer name length is MAX_COMPUTERNAME_LENGTH (15). This length does not include the trailing dollar sign ($).
  • The password for a new computer account should be the lowercase representation of the computer account name, without the trailing dollar sign ($). For interdomain trust, the password can be an arbitrary value that matches the value specified on the trust side of the relationship.
  • The maximum password length is LM20_PWLEN (14). The password should be truncated to this length if the computer account name exceeds this length.
  • The password provided at computer-account-creation time is valid only until the computer account becomes active on the domain. A new password is established during trust relationship activation.
#include <windows.h>
#include <lm.h>

BOOL AddMachineAccount(
    LPWSTR wTargetComputer,
    LPWSTR MachineAccount,
    DWORD AccountType
    )
{
    LPWSTR wAccount;
    LPWSTR wPassword;
    USER_INFO_1 ui;
    DWORD cbAccount;
    DWORD cbLength;
    DWORD dwError;

    //
    // Ensure a valid computer account type was passed.
    //
    if (AccountType != UF_WORKSTATION_TRUST_ACCOUNT &&
        AccountType != UF_SERVER_TRUST_ACCOUNT &&
        AccountType != UF_INTERDOMAIN_TRUST_ACCOUNT
        )
    {
        SetLastError(ERROR_INVALID_PARAMETER);
        return FALSE;
    }

    //
    // Obtain number of chars in computer account name.
    //
    cbLength = cbAccount = lstrlenW(MachineAccount);

    //
    // Ensure computer name doesn't exceed maximum length.
    //
    if(cbLength > MAX_COMPUTERNAME_LENGTH) {
        SetLastError(ERROR_INVALID_ACCOUNT_NAME);
        return FALSE;
    }

    //
    // Allocate storage to contain Unicode representation of
    // computer account name + trailing $ + NULL.
    //
    wAccount=(LPWSTR)HeapAlloc(GetProcessHeap(), 0,
        (cbAccount + 1 + 1) * sizeof(WCHAR)  // Account + '$' + NULL
        );

    if(wAccount == NULL) return FALSE;

    //
    // Password is the computer account name converted to lowercase;
    //  you will convert the passed MachineAccount in place.
    //
    wPassword = MachineAccount;

    //
    // Copy MachineAccount to the wAccount buffer allocated while
    //  converting computer account name to uppercase.
    //  Convert password (in place) to lowercase.
    //
    while(cbAccount--) {
        wAccount[cbAccount] = towupper( MachineAccount[cbAccount] );
        wPassword[cbAccount] = towlower( wPassword[cbAccount] );
    }

    //
    // Computer account names have a trailing Unicode '$'.
    //
    wAccount[cbLength] = L'$';
    wAccount[cbLength + 1] = L'\0'; // terminate the string

    //
    // If the password is greater than the max allowed, truncate.
    //
    if(cbLength > LM20_PWLEN) wPassword[LM20_PWLEN] = L'\0';

    //
    // Initialize the USER_INFO_1 structure.
    //
    ZeroMemory(&ui, sizeof(ui));

    ui.usri1_name = wAccount;
    ui.usri1_password = wPassword;

    ui.usri1_flags = AccountType | UF_SCRIPT;
    ui.usri1_priv = USER_PRIV_USER;

    dwError=NetUserAdd(
                wTargetComputer,    // target computer name
                1,                  // info level
                (LPBYTE) &ui,       // buffer
                NULL
                );

    //
    // Free allocated memory.
    //
    if(wAccount) HeapFree(GetProcessHeap(), 0, wAccount);

    //
    // Indicate whether the function was successful.
    //
    if(dwError == NO_ERROR)
        return TRUE;
    else {
        SetLastError(dwError);
        return FALSE;
    }
}

The user that calls the account management functions must have Administrator privilege on the target computer. In the case of existing computer accounts, the creator of the account can manage the account, regardless of administrative membership.

The SeMachineAccountPrivilege can be granted on the target computer to give specified users the ability to create computer accounts. This gives non-administrators the ability to create computer accounts. The caller needs to enable this privilege prior to adding the computer account.


Creating a Local Group and Adding a User

Windows NT/Windows 2000 and Windows NT Server/Windows 2000 Server use the same functions that Microsoft LAN Manager uses to create and maintain user and local group-account information. A member of a Users group can create, maintain, and delete accounts in local groups. For example, to create a new local group, call the NetLocalGroupAdd function. To add a user to that group, call the NetLocalGroupAddMembers function.

The following program allows you to create a user and a local group and add the user to the local group.

#define UNICODE 1
#include <windows.h>
#include <lmcons.h>
#include <lmaccess.h>
#include <lmerr.h>
#include <lmapibuf.h>
#include <stdio.h>
#include <stdlib.h>

int _CRTAPI1 main( int cArgs, char *pArgs[] );

NET_API_STATUS NetSample( LPWSTR lpszDomain,
                          LPWSTR lpszUser,
                          LPWSTR lpszPassword,
                          LPWSTR lpszLocalGroup )
{

    USER_INFO_1               user_info;
    LOCALGROUP_INFO_1         localgroup_info;
    LOCALGROUP_MEMBERS_INFO_3 localgroup_members;
    LPWSTR                    lpszPrimaryDC = NULL;
    NET_API_STATUS            err = 0;
    DWORD                     parm_err = 0;

// First get the name of the primary domain controller.
// Be sure to free the returned buffer.

    err = NetGetDCName( NULL,                   // Local machine
                   lpszDomain,                  // Domain name
                   (LPBYTE *)&lpszPrimaryDC );  // Returned PDC

    if ( err != 0 )
    {
        printf( "Error getting DC name: %d\n", err );
        return( err );
    }

// Set up the USER_INFO_1 structure.

    user_info.usri1_name = lpszUser;
    user_info.usri1_password = lpszPassword;
    user_info.usri1_priv = USER_PRIV_USER;
    user_info.usri1_home_dir = TEXT("");
    user_info.usri1_comment = TEXT("Sample User");
    user_info.usri1_flags = UF_SCRIPT;
    user_info.usri1_script_path = TEXT("");

    err = NetUserAdd( lpszPrimaryDC,       // PDC name
                      1,                   // Level
                      (LPBYTE)&user_info,  // Input buffer
                      &parm_err );         // Parameter in error

    switch ( err )
    {
    case 0:
        printf("user successfully created.\n");
        break;
    case NERR_UserExists:
        printf("user already exists.\n");
        err = 0;
        break;
    case ERROR_INVALID_PARAMETER:
        printf("Invalid Parameter Error adding user:
        Parameter Index = %d\n",
                parm_err);
        NetApiBufferFree( lpszPrimaryDC );
        return( err );
    default:
        printf("Error adding user: %d\n", err);
        NetApiBufferFree( lpszPrimaryDC );
        return( err );
    }

// Set up the LOCALGROUP_INFO_1 structure.

    localgroup_info.lgrpi1_name = lpszLocalGroup;
    localgroup_info.lgrpi1_comment = TEXT("Sample Local group.");

    err = NetLocalGroupAdd( lpszPrimaryDC,    // PDC name
                  1,                          // Level
                  (LPBYTE)&localgroup_info,   // Input buffer
                  &parm_err );                // Parameter in error

    switch ( err )
    {
    case 0:
        printf("Local Group successfully created.\n");
        break;
    case ERROR_ALIAS_EXISTS:
        printf("Local Group already exists.\n");
        err = 0;
        break;
    case ERROR_INVALID_PARAMETER:
        printf("Invalid Parameter Error adding Local Group:
        Parameter Index = %d\n",
                err, parm_err);
        NetApiBufferFree( lpszPrimaryDC );
        return( err );
    default:
        printf("Error adding Local Group: %d\n", err);
        NetApiBufferFree( lpszPrimaryDC );
        return( err );
    }

// Now add the user to the local group.

    localgroup_members.lgrmi3_domainandname = lpszUser;

    err = NetLocalGroupAddMembers( lpszPrimaryDC,      // PDC name
                           lpszLocalGroup,             // Group name
                           3,                          // Name
                           LPBYTE)&localgroup_members, // Buffer
                           1 );                        // Count

    switch ( err )
    {
    case 0:
        printf("User successfully added to Local Group.\n");
        break;
    case ERROR_MEMBER_IN_ALIAS:
        printf("User already in Local Group.\n");
        err = 0;
        break;
    default:
        printf("Error adding User to Local Group: %d\n", err);
        break;
    }

    NetApiBufferFree( lpszPrimaryDC );
    return( err );
}

int _CRTAPI1 main( int    cArgs,
                   char * pArgs[] )
{
    NET_API_STATUS err = 0;

    printf( "Calling NetSample.\n" );
    err = NetSample( TEXT("SampleDomain"),
                     TEXT("SampleUser"),
                     TEXT("SamplePswd"),
                     TEXT("SampleLG") );
    printf( "NetSample returned %d\n", err );
    return( 0 );
}


Determining the Validating Server on Windows 95/98

Determining the Windows NT/Windows 2000 domain server that validates a user's logon password from Windows 95/98 is an involved task. The code sample in this topic demonstrates how to determine the validating server for a Windows 95/98 user, using the 16-bit network management functions.

On Windows NT/Windows 2000, the 32-bit NetWkstaUserGetInfo function determines the validating server. The function uses level 1 to return a WKSTA_USER_INFO_1 structure. The wkui1_logon_server member will contain a pointer to a Unicode string specifying the validating server.

On Windows 95/98, there is no 32-bit function that will return the same information. You must use the 16-bit network management functions to retrieve the same information. The functions are exported from Netapi.dll. The link libraries are included with the 16-bit version of Microsoft® Visual C++ (version 1.5x).

To determine the validating server on Windows 95/98

Use the following basic steps, making calls to the 16-bit network management functions:

  1. Determine the user's logon domain using NetWkstaGetInfo.
  2. Find the primary domain controller (PDC) using NetGetDCName.
  3. Get the user information from the PDC for comparison to the backup domain controller (BDC) data using NetUserGetInfo.
  4. Get a list of BDCs using the NetServerEnum function.
  5. Loop through the list of BDCs, using NetUserGetInfo to retrieve the specific user information, comparing each last logon time, searching for the greatest value.

The largest last logon value will be the latest logon time; it will be associated with the last server to validate the user's logon password.

The following short 16-bit program illustrates how to determine the validating server for a Windows 95/98 user.

Note You must use the LAN.H and the NETAPI.LIB files distributed with the SDK for the following code sample to work. The user must be certain that the directories for the .H and .LIB files are in the search path for the project.

#include <windows.h>
#include <stdio.h>
#include <string.h>
#include <stdlib.h>
#include <time.h>
#define INCL_NET
#include <lan.h>

// Constant definitions.

#define LEVEL_01 1
#define LEVEL_11 11
#define LEVEL_10 10
#define LEVEL_00 0

#define SMALL_BUFFER 1024
#define MEDIUM_BUFFER 4*1024
#define SERVER_NAME  50

// Buffer allocation performed globally for simplicity.

LPSTR bdcNames[SMALL_BUFFER];
LPSTR UserData[MEDIUM_BUFFER];
LPSTR WrkSta[SMALL_BUFFER];
LPSTR pdcName[SERVER_NAME];
LPSTR servername[SERVER_NAME];

// Create a structure to hold the current server and
//  the logon time so the values are together.

typedef struct svr_usr {
    LPSTR server;
    long logon_time;
} SVR_USR;

// Create typedefs for the larger structure names to
//  shorten the number of characters to type.

typedef struct user_info_11  USER11;
typedef struct wksta_info_10 WORK10;
typedef struct wksta_info_1 WORK01;
typedef struct server_info_100 SERVER100;
typedef struct tm TIMER;

// Declare pointers so the buffers returned from the system
//  functions can be cast to an appropriate value.

//   Global variable descriptions.
//     Users:   Pointer to a USER_INFO_11 structure that contains user
//              information about the username derived from the Wksta
//              array. The element of interest is usri11_last_logon, the
//              time that the server last validated the user's
//              password.
//     Wksta:   Pointer to the WKSTA_INFO_10 structure that contains
//              information about the WFW workstation. This structure is
//              filled first, and the information placed there is used
//              to get additional information. The domain name is used
//              to get a list of BDCs that will be queried for user
//              data. The username is the element that will qualify the
//              user data request. The elements of interest are
//              wki10_username, the current logged-on user, and
//              wki10_logon_domain, the domain in which the user
//              has logged on.
//     Servers: List of BDCs for the user's logon domain. Each
//              server in the array will be queried for information
//              about the current logged-on user as described
//              in the user's variable comments.
//

TIMER  *lpTime;
USER11  far *Users;
WORK10  far *Wksta;
SERVER0 far *Servers;
WORK01  far *Wksta01;

char * lpszTime;

// Declare values for use with the network management functions.

unsigned short svrEntries;
unsigned short svrRead;
unsigned short usrEntries;
unsigned short wkstaEntries;

// Create a temporary variable to use as a loop control variable.

unsigned short i;

char Message[256];

// Define a global variable to hold the validating server
//  and the time the user last logged on.

SVR_USR validate = { NULL, 0 };

// Create a global variable for the return value of the function;
//  this is used in error checking.

DWORD netRet;

// Bogus WinMain so you can step through the sample
//  in a 16-bit debugger.

int PASCAL WinMain(hInstance, hPrevInstance, lpCmdLine, nCmdShow)
HANDLE hInstance;                // current instance
HANDLE hPrevInstance;            // previous instance
LPSTR lpCmdLine;                 // command line
int nCmdShow;                    // show-window type (open/icon)
{
   // First, get the workstation information calling
   //  the NetWkstaGetInfo function at level 10.
   //  This will return the domain in which the user logged on.

   netRet = NetWkstaGetInfo( NULL,  // This workstation
                         LEVEL_10,  // Information requested
               (char far *)WrkSta,  // Buffer
                     SMALL_BUFFER,
                    &wkstaEntries); // Expecting only 1 entry

   if( netRet != NERR_Success )
   {
      // A network error occurred. Print it to the stdout.

      sprintf(Message,"ERROR: NetWkstaGetInfo API Failed. Error Code: %d\n", netRet);
      MessageBox( NULL, Message, "NetWkstaGetInfo Error", MB_OK);
      return(0);
   }

   // Now we must retrieve the BDCs and the PDC to check
   //  when the last user logon was validated.
   //
   // The argument list is set as follows:
   //   Execute on the local machine ( NULL )
   //   Pass the domain name of interest (Wksta[0].wki10_logon_domain)
   //   Pass a buffer to receive the PDC name
   //   Pass the size of the PDC name buffer

   Wksta = (WORK10 *)WrkSta;
   netRet = NetGetDCName( NULL,
                          Wksta[0].wki10_logon_domain,
                          (char far *)pdcName,
                          SERVER_NAME);
   if(netRet != NERR_Success )
   {
      // Could not locate a PDC. Something is wrong; end the program.

      sprintf(Message,"ERROR: NetGetDCName API Failed. Error Code: %d\n", netRet);
      MessageBox( NULL, Message, "NetGetDCName Error", MB_OK);
      return(0);
   }

   // We have the PDC. Now, query for the user information,
   //   and store it temporarily for comparison to the BDC's data.

   netRet = NetUserGetInfo( (char far *)pdcName,  // Execute on the PDC
                            Wksta[0].wki10_username, // User's name
                            LEVEL_11,
                            (char far *)UserData, // Put structures here
                            SMALL_BUFFER,
                            &usrEntries); // Expecting only one entry
   if( netRet != NERR_Success )
   {
       // No user account on the PDC. End the program.

      sprintf(Message,"ERROR: NetUserGetInfo API Failed on PDC. Error Code: %d\n", netRet);
      MessageBox( NULL, Message, "NetUserGetInfo Error", MB_OK);
      return(0);
   }

   // Set the structure so the PDC is the starting validating server.

   validate.server =  (char far *)pdcName;
   Users = (USER11 * )UserData;
   validate.logon_time = Users[0].usri11_last_logon;

   // Now retrieve all of the BDCs.

   netRet = NetServerEnum2(  NULL,
                             LEVEL_00,
                             (char far *)bdcNames,
                             SMALL_BUFFER,
                             &svrRead,
                             &svrEntries,
                             SV_TYPE_DOMAIN_BAKCTRL,
                             Wksta[0].wki10_logon_domain);

   if( netRet != NERR_Success )
   {
      // No BDCs. This could be an error.

      sprintf(Message,"ERROR: NetServerEnum2 API Failed. Error Code: %d", netRet);
      MessageBox( NULL, Message, "NetServerEnum2", MB_OK);
      return( 0 );
   }

   // We have a list of BDCs.
   // If svrEntries > 1
   //    loop through the list, checking the last logon against the
   //     current logon stored in validate.logon_time.

   Servers =( SERVER0 * )bdcNames;
   for( i = 0; i < svrEntries; i++ )
   {
      // Must add the \\ to the names returned from the NetServerEnum function.

      _fstrcpy( (LPSTR)servername,"\\\\");
      _fstrcat( (LPSTR)servername,Servers[i].sv0_name);
      netRet = NetUserGetInfo( (LPSTR)servername,  // Execute on a BDC
                         Wksta[0].wki10_username,  // User's name
                         LEVEL_11,
                         (char far *)UserData,
                         SMALL_BUFFER,
                         &usrEntries); // Expecting only one entry
      Users = (USER11 *)UserData;
      if( netRet == NERR_Success )
      {
         // We found a user entry on this BDC. Compare the
         //  last logon time to the stored time. Replace the stored
         //  time if the time is greater.
         //
         // Replace the servername so the time and the server match.

         if( Users[0].usri11_last_logon > validate.logon_time)
         {
            validate.server = (char far *)&Servers[i];
            validate.logon_time = Users[0].usri11_last_logon;
         }
         else if( Users[0].usri11_last_logon == validate.logon_time )
         {
            // This could indicate a problem.

            sprintf(Message,"Values are the same. %ls %ls", Servers[i].sv0_name, validate.server);
            MessageBox( NULL, Message, "HMMMM...........",MB_OK);
         }
      }
   }

   // Convert the time in seconds to a time structure for display;
   //  build the output string.

    lpTime = gmtime( &validate.logon_time);
    lpszTime = asctime( lpTime );
    _fstrcpy((LPSTR)Message, (LPSTR)"Username: ");
    _fstrcat((LPSTR)Message, (LPSTR)Wksta[0].wki10_username);
    _fstrcat((LPSTR)Message, (LPSTR)"\nLast Logon: ");
    _fstrcat((LPSTR)Message, (LPSTR)lpszTime);
    _fstrcat((LPSTR)Message, (LPSTR)"Logon Server: ");
    _fstrcat((LPSTR)Message, (LPSTR)validate.server);

    // Display the information.

    MessageBox(NULL,Message,"Logon Validation Information", MB_OK);
    return(0);
}


Looking Up Text for Error Code Numbers

In Windows NT/Windows 2000, it is sometimes necessary to display error text associated with error codes returned from networking-related functions. You may need to perform this task with the network management functions provided by the system.

The error text for these messages is found in the message table file named Netmsg.dll, which is found in %systemroot%\system32. This file contains error messages in the range NERR_BASE (2100) through MAX_NERR(NERR_BASE+899). These error codes are defined in the SDK header file lmerr.h.

The LoadLibrary and LoadLibraryEx Win32 functions can load Netmsg.dll. The FormatMessage Win32 function maps an error code to message text, given a module handle to the Netmsg.dll file.

The following sample illustrates how to display error text associated with network management functions, in addition to displaying error text associated with system-related error codes. If the supplied error number is in a specific range, the netmsg.dll message module is loaded and used to look up the specified error number with the FormatMessage function.

#include <windows.h>
#include <stdio.h>

#include <lmerr.h>

void
DisplayErrorText(
    DWORD dwLastError
    );

#define RTN_OK 0
#define RTN_USAGE 1
#define RTN_ERROR 13

int
__cdecl
main(
    int argc,
    char *argv[]
    )
{
    if(argc != 2) {
        fprintf(stderr,"Usage: %s <error number>\n", argv[0]);
        return RTN_USAGE;
    }

    DisplayErrorText( atoi(argv[1]) );

    return RTN_OK;
}

void
DisplayErrorText(
    DWORD dwLastError
    )
{
    HMODULE hModule = NULL; // default to system source
    LPSTR MessageBuffer;
    DWORD dwBufferLength;

    DWORD dwFormatFlags = FORMAT_MESSAGE_ALLOCATE_BUFFER |
        FORMAT_MESSAGE_IGNORE_INSERTS |
        FORMAT_MESSAGE_FROM_SYSTEM ;

    //
    // If dwLastError is in the network range,
    //  load the message source.
    //

    if(dwLastError >= NERR_BASE && dwLastError <= MAX_NERR) {
        hModule = LoadLibraryEx(
            TEXT("netmsg.dll"),
            NULL,
            LOAD_LIBRARY_AS_DATAFILE
            );

        if(hModule != NULL)
            dwFormatFlags |= FORMAT_MESSAGE_FROM_HMODULE;
    }

    //
    // Call FormatMessage() to allow for message
    //  text to be acquired from the system
    //  or from the supplied module handle.
    //

    if(dwBufferLength = FormatMessageA(
        dwFormatFlags,
        hModule, // module to get message from (NULL == system)
        dwLastError,
        MAKELANGID(LANG_NEUTRAL, SUBLANG_DEFAULT), // default language
        (LPSTR) &MessageBuffer,
        0,
        NULL
        ))
    {
        DWORD dwBytesWritten;

        //
        // Output message string on stderr.
        //
        WriteFile(
            GetStdHandle(STD_ERROR_HANDLE),
            MessageBuffer,
            dwBufferLength,
            &dwBytesWritten,
            NULL
            );

        //
        // Free the buffer allocated by the system.
        //
        LocalFree(MessageBuffer);
    }

    //
    // If we loaded a message source, unload it.
    //
    if(hModule != NULL)
        FreeLibrary(hModule);
}

After you compile this program, you can insert the error code number as an argument and the program will display the text. For example:

C:\> netmsg 2453
Could not find domain controller for this domain


Windows 95/98 Network Management Code Samples

The following code samples demonstrate how to use the 32-bit network management functions that are supported by Windows 95 and Windows 98. (You can find code samples demonstrating the network management functions supported by Windows NT/Windows 2000 on the appropriate reference page.)

  • NetConnectionEnum Sample
  • NetFileEnum Sample
  • NetSecurityGetInfo Sample
  • NetServerGetInfo Sample
  • NetSessionDel Sample
  • NetSessionEnum Sample
  • NetSessionGetInfo Sample
  • NetShareAdd Sample
  • NetShareDel Sample
  • NetShareEnum Sample
  • NetShareGetInfo Sample
  • NetShareSetInfo Sample


NetConnectionEnum Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to list the connections made to a shared resource with a call to the NetConnectionEnum function.

The sample allocates the memory required to receive 20 connection_info_50 structures. If this size is inadequate, the sample warns the caller that there are more entries to enumerate. Finally, the sample frees the allocated memory.

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <svrapi.h>

const short MAX_ENTRIES = 20;

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   char FAR * pszQualifier = NULL;
   short nLevel = 50;
   struct connection_info_50* pBuf = NULL;
   struct connection_info_50* pTmpBuf = NULL;
   short cbBuffer;
   short nEntriesRead = 0;
   short nTotalEntries = 0;
   short nTotalCount = 0;
   int i;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer; ShareName
   //   is required.
   //
   if((argc < 2) || (argc > 3))
   {
      printf("Usage: %s [ServerName] ShareName | \\\\ComputerName\n", argv[0]);
      exit(0);
   }

   if(argc == 3)
      pszServerName=argv[1];

   pszQualifier=argv[argc - 1];
   //
   // Allocate the memory required to receive a maximum of
   //  20 connection_info_50 structures.
   //
   cbBuffer = MAX_ENTRIES * sizeof(struct connection_info_50);

   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");

   // Call the NetConnectionEnum function to list the
   //  connections, specifying information level 50.
   //
   nStatus = NetConnectionEnum(pszServerName,
                               pszQualifier,
                               nLevel,
                               (char FAR *)pBuf,
                               cbBuffer,
                               &nEntriesRead,
                               &nTotalEntries);
   //
   // Loop through the entries; process errors.
   //
   if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
   {
      if ((pTmpBuf = pBuf) != NULL)
      {
         for (i = 0; (i < nEntriesRead); i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Display information for each entry retrieved.
            //
            printf("\n\tNet Name: %s\n", pTmpBuf->coni50_netname);
            printf("\n\tUser Name: %s\n", pTmpBuf->coni50_username);

            pTmpBuf++;
            nTotalCount++;
         }
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Display a warning if the buffer was not large enough
   //  to contain all available entries.
   //
   if ((nEntriesRead < nTotalEntries) || (nStatus == ERROR_MORE_DATA))
      fprintf(stderr, "Not all entries have been enumerated\n");
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   fprintf(stderr, "\nTotal of %d entries enumerated\n", nTotalCount);

   return 0;
}


NetFileEnum Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to list the open files on a server with a call to the NetFileEnum function.

The sample allocates the memory required to receive 20 file_info_50 structures. If this size is inadequate, the sample warns the caller that there are more entries to enumerate. Finally, the sample frees the allocated memory.

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <svrapi.h>

const short MAX_ENTRIES = 20;

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   short nLevel = 50;
   struct file_info_50* pBuf = NULL;
   struct file_info_50* pTmpBuf = NULL;
   short cbBuffer;
   short nEntriesRead = 0;
   short nTotalEntries = 0;
   short nTotalCount = 0;
   int i;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if (argc > 2)
   {
      printf("Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }

   if (argc == 2)
      pszServerName = argv[1];
   //
   // Allocate the memory required to receive a maximum of
   //  20 file_info_50 structures.
   //
   cbBuffer = MAX_ENTRIES * sizeof(struct file_info_50);

   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");

   // Call the NetFileEnum function to list the
   //  open files, specifying information level 50.
   //
   nStatus = NetFileEnum(pszServerName,
                         NULL,
                         nLevel,
                         (char FAR *)pBuf,
                         cbBuffer,
                         &nEntriesRead,
                         &nTotalEntries);
   //
   // Loop through the entries; process errors.
   //
   if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
   {
      if ((pTmpBuf = pBuf) != NULL)
      {
         for (i = 0; (i < nEntriesRead); i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Display the information for each entry retrieved.
            //
            printf("\tShare: %s\n", pTmpBuf->fi50_sharename);
            printf("\n\tPath: %s\n", pTmpBuf->fi50_pathname);
            printf("\tUser:   %s\n", pTmpBuf->fi50_username);
            printf("\tID:   %d\n", pTmpBuf->fi50_id);

            pTmpBuf++;
            nTotalCount++;
         }
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Display a warning if the buffer was not large enough
   //  to contain all available entries.
   //
   if ((nEntriesRead < nTotalEntries) || (nStatus == ERROR_MORE_DATA))
      fprintf(stderr, "Not all entries have been enumerated\n");
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   fprintf(stderr, "\nTotal of %d entries enumerated\n", nTotalCount);

   return 0;
}


NetSecurityGetInfo Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates use of the NetSecurityGetInfo function.

The code sample specifies the security_info_1 information level. The example allocates and frees the memory required for the information buffer.

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <svrapi.h>

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   short nLevel = 1;
   struct security_info_1* pBuf = NULL;
   unsigned short cbBuffer;
   unsigned short nTotalAvail = 0;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if (argc > 2)
   {
      printf("Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }

   if (argc == 2)
      pszServerName = argv[1];
   //
   // Allocate the memory for the buffer.
   //
   cbBuffer = sizeof(struct security_info_1);

   pBuf = (struct security_info_1*)malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");
   //
   // Call the NetSecurityGetInfo function,
   //  specifying information level 1.
   //
   nStatus = NetSecurityGetInfo(pszServerName,
                                nLevel,
                                (char FAR *)pBuf,
                                cbBuffer,
                                &nTotalAvail);
   //
   // If the call is successful, display the data.
   //
   if (nStatus == NERR_Success)
   {
      printf("\n\tContainer: %s\n", pBuf->sec1_container);
      printf("\tAddress book server: %s\n", pBuf->sec1_ab_server);
      printf("\tAddress book provider DLL: %s\n", pBuf->sec1_ab_dll);
        if (pBuf->sec1_security == SEC_SECURITY_SHARE)
         printf("\tSecurity: Share-level\n");
        else // SEC_SECURITY_WINNT, SEC_SECURITY_WINNTAS, or SEC_SECURITY_NETWARE
         printf("\tSecurity: User-level\n");
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   return 0;
}


NetServerGetInfo Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to retrieve a server's configuration information using a call to the NetServerGetInfo function.

The sample calls NetServerGetInfo once to determine the size of the buffer needed for the returned data. The code allocates memory for the buffer. Then the sample calls NetServerGetInfo again to retrieve the data. Finally, the sample displays the information and frees the allocated memory.

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <svrapi.h>

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   short nLevel = 50;
   struct server_info_50* pBuf = NULL;
   unsigned short cbBuffer;
   unsigned short nTotalAvail;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if (argc > 2)
   {
      printf("Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }

   if (argc == 2)
      pszServerName = argv[1];
   //
   // Call NetServerGetInfo once to determine the
   //   total size needed for the buffer.
   //
   cbBuffer = 0;
   nStatus = NetServerGetInfo(pszServerName,
                              nLevel,
                              (char FAR *)pBuf,
                              cbBuffer,
                              &nTotalAvail);

   if (nStatus != NERR_BufTooSmall)
   {
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      exit(1);
   }
   //
   // Allocate the memory required for the buffer.
   //
   cbBuffer = nTotalAvail;

   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");
   //
   // Call NetServerGetInfo a second time to retrieve the
   //  information, specifying information level 50.
   //
   nStatus = NetServerGetInfo(pszServerName,
                              nLevel,
                              (char FAR *)pBuf,
                              cbBuffer,
                              &nTotalAvail);
   //
   // If the call is successful, display the data.
   //
   if (nStatus == NERR_Success)
   {
      printf("\tName: %s\n", pBuf->sv50_name);
      printf("\tVersion: %d.%d\n", pBuf->sv50_version_major,pBuf->sv50_version_minor);
      printf("\tType: 0x%x\n", pBuf->sv50_type);
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   return 0;
}


NetSessionDel Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to terminate a session with a call to the NetSessionDel function.

#include <stdio.h>
#include <windows.h>
#include <svrapi.h>

int main(int argc, char FAR * argv[])
{
   DWORD dwError = 0;
   char FAR * pszServerName = NULL;
   char FAR * pszClientName = NULL;
   short nSessionKey = -1;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //

   if ((argc < 3) || (argc > 4))
   {
      printf("Usage: %s  ClientName SessionKey [\\\\ServerName]\n", argv[0]);
      printf("Note: ClientName is case sensitive\n");
      exit(1);
   }

   pszClientName = argv[1];
   nSessionKey = atoi(argv[2]);

   if (argc == 4)
      pszServerName = argv[3];
   //
   // Call the NetSessionDel function to terminate the session.
   //
   nStatus = NetSessionDel(pszServerName,
                           pszClientName,
                           nSessionKey);
   //
   // Display the result of the function call.
   //
   if (nStatus == NERR_Success)
      fprintf(stderr, "The specified session(s) has been successfully deleted\n");
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}


NetSessionEnum Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to list the current sessions on a server with a call to the NetSessionEnum function.

The sample allocates the memory required to receive 20 session_info_50 structures. If this size is inadequate, the sample warns the caller that there are more entries to enumerate. Finally, the sample frees the allocated memory.

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <svrapi.h>

const short MAX_ENTRIES = 20;

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   short nLevel = 50;
   struct session_info_50* pBuf = NULL;
   struct session_info_50* pTmpBuf = NULL;
   short cbBuffer;
   short nEntriesRead = 0;
   short nTotalEntries = 0;
   short nTotalCount = 0;
   int i;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if (argc > 2)
   {
      printf("Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }

   if (argc == 2)
      pszServerName = argv[1];

   cbBuffer = MAX_ENTRIES * sizeof(struct session_info_50);
   //
   // Allocate the memory required to receive a maximum of
   //  20 session_info_50 structures.
   //
   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");

   // Call the NetSessionEnum function to list the
   //  sessions, specifying information level 50.
   //
   nStatus = NetSessionEnum(pszServerName,
                            nLevel,
                            (char FAR *)pBuf,
                            cbBuffer,
                            &nEntriesRead,
                            &nTotalEntries);
   //
   // Loop through the entries; process errors.
   //
   if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
   {
      if ((pTmpBuf = pBuf) != NULL)
      {
         for (i = 0; (i < nEntriesRead); i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Display the information for each entry retrieved.
            //
            printf("\n\tClient: %s\n", pTmpBuf->sesi50_cname);
            printf("\tUser:   %s\n", pTmpBuf->sesi50_username);
            printf("\tActive: %d\n", pTmpBuf->sesi50_time);
            printf("\tIdle:   %d\n", pTmpBuf->sesi50_idle_time);
            printf("\tKey:   %d\n", pTmpBuf->sesi50_key);

            pTmpBuf++;
            nTotalCount++;
         }
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Display a warning if the buffer was not large enough
   //  to contain all available entries.
   //
   if ((nEntriesRead < nTotalEntries) || (nStatus == ERROR_MORE_DATA))
      fprintf(stderr, "Not all entries have been enumerated\n");
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   fprintf(stderr, "\nTotal of %d entries enumerated\n", nTotalCount);

   return 0;
}


NetSessionGetInfo Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to retrieve information about a particular session using a call to the NetSessionGetInfo function.

The sample calls NetSessionGetInfo once to determine the size of the buffer needed for the returned data. The code allocates memory for the buffer. Then the sample calls NetSessionGetInfo again to retrieve the data. Finally, the sample displays the information and frees the allocated memory.

#include <stdio.h>
#include <windows.h>
#include <svrapi.h>

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   short nLevel = 50;
   struct session_info_50* pBuf = NULL;
   unsigned short cbBuffer;
   unsigned short nTotalAvail;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if ((argc < 2) || (argc > 3))
   {
      printf("Usage: %s [\\\\ServerName] \\\\ClientName\n", argv[0]);
      exit(1);
   }

   if (argc == 3)
      pszServerName = argv[1];
   //
   // Call NetSessionGetInfo once to determine the
   //   total size needed for the buffer.
   //
   cbBuffer = 0;
   nStatus = NetSessionGetInfo(pszServerName,
                               argv[argc-1],
                               nLevel,
                               (char FAR *)pBuf,
                               cbBuffer,
                               &nTotalAvail);

   if (nStatus != NERR_BufTooSmall)
   {
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      exit(1);
   }
   //
   // Allocate the memory required for the buffer.
   //
   cbBuffer = nTotalAvail;
   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");
   //
   // Call NetSessionGetInfo a second time to retrieve the
   //  information, specifying information level 50.
   //
   nStatus = NetSessionGetInfo(pszServerName,
                               argv[argc-1],
                               nLevel,
                               (char FAR *)pBuf,
                               cbBuffer,
                               &nTotalAvail);
   //
   // If the call is successful, display the data.
   //
   if (nStatus == NERR_Success)
   {
      printf("\n\tComputer: %s\n", pBuf->sesi50_cname);
      printf("\tUser: %s\n", pBuf->sesi50_username);
      printf("\tKey: %d\n", pBuf->sesi50_key);
      printf("\t# Connections: %d\n", pBuf->sesi50_num_conns);
      printf("\t# Opens: %d\n", pBuf->sesi50_num_opens);
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   return 0;
}


NetShareAdd Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to share a resource on the local computer with a call to the NetShareAdd function.

The code sample specifies the share_info_50 structure and no password on the share. The sample also allocates and frees the memory required for the information buffer.

#include <stdio.h>
#include <windows.h>
#include <svrapi.h>

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   short nLevel = 50;
   struct share_info_50* pBuf = NULL;
   unsigned short cbBuffer;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if ((argc < 3) || (argc > 4))
   {
      printf("Usage: %s [\\\\ServerName] ShareName SharePath\n", argv[0]);
      exit(1);
   }

   if (argc == 4)
      pszServerName = argv[1];
   //
   // Allocate the memory required to specify a
   //   share_info_50 structure.
   //
   cbBuffer = sizeof(struct share_info_50);
   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");
   //
   // Assign values to the share_info_50 structure.
   //
   strcpy(pBuf->shi50_netname, argv[argc-2]);
   pBuf->shi50_type = STYPE_DISKTREE;
   pBuf->shi50_flags = SHI50F_FULL;
   pBuf->shi50_remark = NULL;
   pBuf->shi50_path = argv[argc-1];
   pBuf->shi50_rw_password[0] = '\0'; // No password
   pBuf->shi50_ro_password[0] = '\0'; // No password
   //
   // Call the NetShareAdd function
   //  specifying information level 50.
   //
   nStatus = NetShareAdd(pszServerName,
                         nLevel,
                         (char FAR *)pBuf,
                         cbBuffer);
   //
   // Display the result of the function call.
   //
   if (nStatus == NERR_Success)
      printf("Share added successfully\n");
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   return 0;
}


NetShareDel Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to delete a share with a call to the NetShareDel function.

#include <stdio.h>
#include <windows.h>
#include <svrapi.h>

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if ((argc < 2) || (argc > 3))
   {
      printf("Usage: %s [\\\\ServerName] ShareName\n", argv[0]);
      exit(1);
   }

   if (argc == 3)
      pszServerName = argv[1];
   //
   // Call the NetShareDel function to delete the share.
   //
   nStatus = NetShareDel(pszServerName,
                         argv[argc-1],
                              0);
   //
   // Display the result of the function call.
   //
   if (nStatus == NERR_Success)
      printf("Share deleted successfully\n");
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}


NetShareEnum Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to list information about each shared resource on a server with a call to the NetShareEnum function.

The sample allocates the memory required to receive 20 share_info_50 structures. If this size is inadequate, the sample warns the caller that there are more entries to enumerate. Finally, the sample frees the allocated memory.

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <svrapi.h>

const short MAX_ENTRIES = 20;

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   short nLevel = 50;
   struct share_info_50* pBuf = NULL;
   struct share_info_50* pTmpBuf = NULL;
   short cbBuffer;
   short nEntriesRead = 0;
   short nTotalEntries = 0;
   short nTotalCount = 0;
   int i;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if (argc > 2)
   {
      printf("Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }

   if (argc == 2)
      pszServerName = argv[1];
   //
   // Allocate the memory required to receive a maximum of
   //  20 share_info_50 structures.
   //
   cbBuffer = MAX_ENTRIES * sizeof(struct share_info_50);

   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");
   //
   // Call the NetShareEnum function to list the
   //  shares, specifying information level 50.
   //
   nStatus = NetShareEnum(pszServerName,
                          nLevel,
                          (char FAR *)pBuf,
                          cbBuffer,
                          &nEntriesRead,
                          &nTotalEntries);
   //
   // Loop through the entries; process errors.
   //
   if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
   {
      if ((pTmpBuf = pBuf) != NULL)
      {
         for (i = 0; (i < nEntriesRead); i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Display the information for each entry retrieved.
            //
            printf("\n\tShare: %s\n", pTmpBuf->shi50_netname);
            printf("\tPath: %s\n", pTmpBuf->shi50_path);

            pTmpBuf++;
            nTotalCount++;
         }
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Display a warning if the buffer was not large enough
   //  to contain all available entries.
   //
   if ((nEntriesRead < nTotalEntries) || (nStatus == ERROR_MORE_DATA))
      fprintf(stderr, "Not all entries have been enumerated\n");
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   fprintf(stderr, "\nTotal of %d entries enumerated\n", nTotalCount);

   return 0;
}


NetShareGetInfo Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to retrieve information about a shared resource with a call to the NetShareGetInfo function.

The sample calls NetShareGetInfo once to determine the size of the buffer needed for the returned data. The code allocates memory for the buffer. Then the sample calls NetShareGetInfo again to retrieve the data. Finally, the sample displays the information and frees the allocated memory.

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <svrapi.h>

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   char FAR * pszNetName = NULL;
   short nLevel = 50;
   struct share_info_50* pBuf = NULL;
   unsigned short cbBuffer;
   unsigned short nTotalAvail;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if ((argc < 2) || (argc > 3))
   {
      printf("Usage: %s [\\\\ServerName] ShareName\n", argv[0]);
      exit(1);
   }

   if (argc == 3)
      pszServerName = argv[1];
   //
   // Note that for a Win9x peer server,
   //   the share name needs to be uppercase.
   //
   pszNetName = argv[argc-1];
   //
   // Call NetShareGetInfo once to determine the
   //   total size needed for the buffer.
   //
   cbBuffer = 0;
   nStatus = NetShareGetInfo(pszServerName,
                             pszNetName,
                             nLevel,
                             (char FAR *)pBuf,
                             cbBuffer,
                             &nTotalAvail);

   if (nStatus != NERR_BufTooSmall)
   {
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      exit(1);
   }
   //
   // Allocate the memory required for the buffer.
   //
   cbBuffer = nTotalAvail;
   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");
   //
   // Call NetShareGetInfo a second time to retrieve the
   //  information, specifying information level 50.
   //
   nStatus = NetShareGetInfo(pszServerName,
                             pszNetName,
                             nLevel,
                             (char FAR *)pBuf,
                             cbBuffer,
                             &nTotalAvail);
   //
   // If the call is successful, display the data.
   //
   if (nStatus == NERR_Success)
      printf("\n\tPath: %s\n", pBuf->shi50_path);
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      free(pBuf);

   return 0;
}


NetShareSetInfo Sample (Windows 95/98)

Windows 95/98/Me: The following code sample demonstrates how to change the parameters associated with a network share using a call to the NetShareSetInfo function.

The sample uses the following basic steps to change the remark associated with a network share:

  1. Determine the size of the buffer needed to receive share information by calling the NetShareGetInfo function.
  2. Retrieve share information by calling the NetShareGetInfo function a second time, specifying information level 50.
  3. Copy the returned information to a second buffer with a call to the CopyMemory function. (This is necessary to prevent resetting share information other than the comment.)
  4. Modify the remark associated with the share by calling the NetShareSetInfo function.

The code also allocates and deallocates the memory required for both buffers.

#include <stdio.h>
#include <windows.h>
#include <svrapi.h>

int main(int argc, char FAR * argv[])
{
   char FAR * pszServerName = NULL;
   char FAR * pszNetName = NULL;
   short nLevel = 50;
   struct share_info_50* pBuf = NULL;
   struct share_info_50* pBufNew = NULL;
   unsigned short cbBuffer;
   unsigned short nTotalAvail;
   NET_API_STATUS nStatus;
   //
   // ServerName can be NULL to indicate the local computer.
   //
   if ((argc < 3) || (argc > 4))
   {
      printf("Usage: %s [\\\\ServerName] ShareName Comment\n", argv[0]);
      exit(1);
   }

   if (argc == 4)
      pszServerName = argv[1];

   // Note that for Win9x peer servers,
   //   the share name needs to be uppercase.
   //
   pszNetName = argv[argc-2];

   // Call the NetShareGetInfo function once to determine the
   //   total size needed for the first buffer.
   cbBuffer = 0;
   nStatus = NetShareGetInfo(pszServerName,
                             pszNetName,
                             nLevel,
                             (char FAR *)pBuf,
                             cbBuffer,
                             &nTotalAvail);
   //
   // Allocate the memory required for the first buffer.
   //
   cbBuffer = nTotalAvail;

   pBuf = malloc(cbBuffer);

   if (pBuf == NULL)
      printf("No memory\n");
   //
   // Call NetShareGetInfo a second time to retrieve the
   //  information, specifying information level 50.
   //
   nStatus = NetShareGetInfo(pszServerName,
                             pszNetName,
                             nLevel,
                             (char FAR *)pBuf,
                             cbBuffer,
                             &nTotalAvail);
   //
   // If the call succeeds, allocate the memory required
   //   for a second buffer.
   //
   if (nStatus == NERR_Success)
   {
      pBufNew = malloc(cbBuffer);

      if (pBufNew == NULL)
         printf("No memory\n");
     //
     // Copy the first buffer to the second buffer.
     //   This is necessary to prevent resetting other share
     //   information when you call NetShareSetInfo.
     //
     CopyMemory(pBufNew, pBuf, cbBuffer);
     //
     // Assign a new value to the comment
     //  associated with the share.
     //
     strcpy(pBufNew->shi50_remark, argv[argc-1]);
      //
      // Call NetShareSetInfo to make changes, specifying
      //   PARMNUM_ALL to reset all information.
      //
      nStatus = NetShareSetInfo(pszServerName,
                                pszNetName,
                                nLevel,
                                (char FAR *)pBufNew,
                                cbBuffer,
                                PARMNUM_ALL);
      //
      // Process errors and
      //  free the memory allocated for the second buffer.
      //
      if (nStatus != NERR_Success)
          fprintf(stderr, "A system error has occurred (NetShareSetInfo): %d\n", nStatus);
      if (pBufNew != NULL)
         free(pBufNew);
   }
   else
      fprintf(stderr, "A system error has occurred (NetShareGetInfo): %d\n", nStatus);
   //
   // Free the memory allocated for the first buffer.
   //
   if (pBuf != NULL)
      free(pBuf);

   return 0;
}


Network Management Reference

The following topics describe the network management functions and their associated data structures.

  • Network Management Functions
  • Network Management Structures
  • Network Management Macros
  • Network Management Error Codes
  • Mapping ADSI Interfaces to the Network Management Functions


Network Management Functions

The network management functions can be grouped as follows.

Alert Functions

NetAlertRaise
NetAlertRaiseEx

API Buffer Functions

NetApiBufferAllocate
NetApiBufferFree
NetApiBufferReallocate
NetApiBufferSize

Directory Service Functions

NetGetJoinableOUs
NetGetJoinInformation
NetJoinDomain
NetRenameMachineInDomain
NetUnjoinDomain
NetValidateName

Distributed File System (Dfs) Functions

NetDfsAdd
NetDfsAddFtRoot
NetDfsAddStdRoot
NetDfsAddStdRootForced
NetDfsEnum
NetDfsGetClientInfo
NetDfsGetInfo
NetDfsManagerInitialize
NetDfsRemove
NetDfsRemoveFtRoot
NetDfsRemoveFtRootForced
NetDfsRemoveStdRoot
NetDfsSetClientInfo
NetDfsSetInfo

Get Functions

NetGetAnyDCName
NetGetDCName
NetGetDisplayInformationIndex
NetQueryDisplayInformation

Group Functions

NetGroupAdd
NetGroupAddUser
NetGroupDel
NetGroupDelUser
NetGroupEnum
NetGroupGetInfo
NetGroupGetUsers
NetGroupSetInfo
NetGroupSetUsers

Local Group Functions

NetLocalGroupAdd
NetLocalGroupAddMembers
NetLocalGroupDel
NetLocalGroupDelMembers
NetLocalGroupEnum
NetLocalGroupGetInfo
NetLocalGroupGetMembers
NetLocalGroupSetInfo
NetLocalGroupSetMembers

Message Functions

NetMessageBufferSend
NetMessageNameAdd
NetMessageNameDel
NetMessageNameEnum
NetMessageNameGetInfo

NetFile Functions

NetFileClose
NetFileClose2
NetFileEnum
NetFileGetInfo

Remote Utility Functions

NetRemoteComputerSupports
NetRemoteTOD

Replicator Functions

NetReplExportDirAdd
NetReplExportDirDel
NetReplExportDirEnum
NetReplExportDirGetInfo
NetReplExportDirLock
NetReplExportDirSetInfo
NetReplExportDirUnlock
NetReplGetInfo
NetReplImportDirAdd
NetReplImportDirDel
NetReplImportDirEnum
NetReplImportDirGetInfo
NetReplImportDirLock
NetReplImportDirUnlock
NetReplSetInfo

Schedule Functions

NetScheduleJobAdd
NetScheduleJobDel
NetScheduleJobEnum
NetScheduleJobGetInfo

Server Functions

NetServerDiskEnum
NetServerEnum
NetServerGetInfo
NetServerSetInfo

Server and Workstation Transport Functions

NetServerComputerNameAdd
NetServerComputerNameDel
NetServerTransportAdd
NetServerTransportAddEx
NetServerTransportDel
NetServerTransportEnum
NetWkstaTransportAdd
NetWkstaTransportDel
NetWkstaTransportEnum

Session Functions

NetSessionDel
NetSessionEnum
NetSessionGetInfo

Share Functions

NetConnectionEnum
NetShareAdd
NetShareCheck
NetShareDel
NetShareEnum
NetShareGetInfo
NetShareSetInfo

Statistics Function

NetStatisticsGet

Use Functions

NetUseAdd
NetUseDel
NetUseEnum
NetUseGetInfo

User Functions

NetUserAdd
NetUserChangePassword
NetUserDel
NetUserEnum
NetUserGetGroups
NetUserGetInfo
NetUserGetLocalGroups
NetUserSetGroups
NetUserSetInfo

User Modals Functions

NetUserModalsGet
NetUserModalsSet

Workstation and Workstation User Functions

NetWkstaGetInfo
NetWkstaSetInfo
NetWkstaUserGetInfo
NetWkstaUserSetInfo
NetWkstaUserEnum

For a list of additional networking functions, see Windows Networking Functions.

Access and Security Functions (Windows 95/98 only)

NetAccessAdd
NetAccessCheck
NetAccessDel
NetAccessEnum
NetAccessGetInfo
NetAccessGetUserPerms
NetAccessSetInfo
NetSecurityGetInfo

Obsolete Functions

NetAuditClear
NetAuditRead
NetAuditWrite
NetConfigGet
NetConfigGetAll
NetConfigSet
NetErrorLogClear
NetErrorLogRead
NetErrorLogWrite
NetLocalGroupAddMember
NetLocalGroupDelMember
NetServiceControl
NetServiceEnum
NetServiceGetInfo
NetServiceInstall


NetAccessAdd

Windows 95/98/Me: The NetAccessAdd function creates a new access-control list (ACL) for a resource.

Windows NT/2000 or later: The NetAccessAdd function is obsolete on Windows NT/Windows 2000. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

Security Requirements

Requires User level security to be enabled.

extern API_FUNCTION
 NetAccessAdd(
  const char FAR * pszServer,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short cbBuffer
);

Parameters

pszServer
Pointer to a string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
sLevel
Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
1 | The pbBuffer parameter points to an access_info_1 structure.

pbBuffer
Pointer to the buffer that contains the access information structure.
cbBuffer
Specifies the size, in bytes, of the buffer pointed to by the pbBuffer parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmaccess.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Access Functions, access_list, access_info_1, NetAccessDel


NetAccessCheck

Windows 95/98/Me: The NetAccessCheck function verifies that a user has permission to perform a specified operation on a particular resource.

Windows NT/2000 or later: The NetAccessCheck function is obsolete on Windows NT/Windows 2000. Win32-based applications should use the AccessCheck function.

Security Requirements

Requires Admin privilege to successfully execute on a computer that has local security enabled.

extern API_FUNCTION
 NetAccessCheck(
  char FAR *pszReserved,
  char FAR *pszUserName,
  char FAR *pszResource,
  unsigned short usOperation,
  unsigned short FAR *pusResult
);

Parameters

pszReserved
This parameter is reserved. It must be NULL.
pszUserName
Pointer to a string that contains a user name.
pszResource
Pointer to a string that contains the name of the network resource.
usOperation
Describes the type of access operation requested. This member can be a combination of the following values.
Value | Meaning
ACCESS_READ | Permission to read data from a resource and, by default, to execute the resource.
ACCESS_WRITE | Permission to write data to the resource.
ACCESS_CREATE | Permission to create an instance of the resource (such as a file); data can be written to the resource when the resource is created.
ACCESS_EXEC | Permission to execute the resource.
ACCESS_DELETE | Permission to delete the resource.
ACCESS_ATRIB | Permission to modify the resource's attributes (such as the date and time when a file was last modified).
ACCESS_PERM | Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user or application.
ACCESS_ALL | Permission to read, write, create, execute, and delete resources, and to modify their attributes and permissions.
ACCESS_GROUP | Permission for a particular group; this value indicates that the entry is for a group.
ACCESS_NONE | The user does not have access to the resource.

pusResult
Pointer to an unsigned short integer that receives a value indicating whether the operation is allowed. This parameter is valid only when the NetAccessCheck function returns NERR_Success. If the user specified by the pszUserName parameter has the required permissions, and the operation is allowed, the value of this parameter is set to zero. In other instances, this parameter is set to ERROR_ACCESS_DENIED.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmaccess.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Access Functions, NetAccessEnum, NetAccessGetInfo


NetAccessDel

Windows 95/98/Me: The NetAccessDel function deletes the access-control list (ACL) for a resource.

Windows NT/2000 or later: The NetAccessDel function is obsolete on Windows NT/Windows 2000. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

Security Requirements

Requires Admin privilege to successfully execute on a computer that has local security enabled.

extern API_FUNCTION
 NetAccessDel(
  const char FAR * pszServer,
  char FAR * pszResource
);

Parameters

pszServer
Pointer to a string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
pszResource
Pointer to a string that contains the name of the network resource for which to remove the access-control list.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmaccess.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Access Functions, NetAccessAdd


NetAccessEnum

Windows 95/98/Me: The NetAccessEnum function retrieves information about each access permission record.

Windows NT/2000 or later: The NetAccessEnum function is obsolete on Windows NT/Windows 2000. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

Security Requirements

Requires Admin privilege to successfully execute on a computer that has local security enabled.

extern API_FUNCTION
 NetAccessEnum(
  const char FAR * pszServer,
  char FAR * pszBasePath,
  short fsRecursive,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short cbBuffer,
  unsigned short FAR * pcEntriesRead,
  unsigned short FAR * pcTotalAvail
);

Parameters

pszServer
Pointer to a string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
pszBasePath
Pointer to a string that contains a base pathname for the resource. A NULL pointer or NULL string means no base path is to be used. The path can be specified as a universal naming convention (UNC) pathname.
fsRecursive
Specifies a flag that enables or disables recursive searching.

If this parameter is equal to zero, the NetAccessEnum function returns entries for the resource named as the base path by the pszBasePath parameter, and for the resources directly below that base path.

If this parameter is nonzero, the function returns entries for all access-control lists (ACLs) that have pszBasePath at the beginning of the resource name.

sLevel
Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | The pbBuffer parameter points to an access_info_0 structure.
1 | The pbBuffer parameter points to an access_info_1 structure.

pbBuffer
Pointer to the buffer that receives the access information structure. The format of this data depends on the value of the sLevel parameter.
cbBuffer
Specifies the size, in bytes, of the buffer pointed to by the pbBuffer parameter.
pcEntriesRead
Pointer to an unsigned short integer that receives the count of elements actually enumerated. The count is valid only if the NetAccessEnum function returns NERR_Success or ERROR_MORE_DATA.
pcTotalAvail
Pointer to an unsigned short integer that receives the total number of entries that could have been enumerated. The count is valid only if the NetAccessEnum function returns NERR_Success or ERROR_MORE_DATA.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmaccess.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Access Functions, access_list, access_info_0, access_info_1, NetAccessCheck, NetAccessGetInfo


NetAccessGetInfo

Windows 95/98/Me: The NetAccessGetInfo function retrieves the access-control list (ACL) for a specified resource.

Windows NT/2000 or later: The NetAccessGetInfo function is obsolete on Windows NT/Windows 2000. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

Security Requirements

Requires Admin privilege to successfully execute on a computer that has local security enabled.

extern API_FUNCTION
 NetAccessGetInfo(
  const char FAR * pszServer,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short cbBuffer,
  unsigned short FAR * pcbTotalAvail
);

Parameters

pszServer
Pointer to a string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
sLevel
Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | The pbBuffer parameter points to an access_info_0 structure.
1 | The pbBuffer parameter points to an access_info_1 structure.

pbBuffer
Pointer to the buffer that receives the access information structure. The format of this data depends on the value of the sLevel parameter.
cbBuffer
Specifies the size, in bytes, of the buffer pointed to by the pbBuffer parameter.
pcbTotalAvail
Pointer to an unsigned short integer that receives the total number of entries available. The count is valid only if the NetAccessGetInfo function returns NERR_Success, NERR_BufTooSmall, or ERROR_MORE_DATA.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmaccess.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Access Functions, access_list, access_info_0, access_info_1, NetAccessEnum, NetAccessSetInfo


NetAccessGetUserPerms

Windows 95/98/Me: The NetAccessGetUserPerms function returns a specified user's or group's access permissions for a particular resource.

Windows NT/2000 or later: The NetAccessGetUserPerms function is obsolete on Windows NT/Windows 2000. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

Security Requirements

Requires Admin privilege to successfully execute on a computer that has local security enabled. When users request their own access permissions no special privilege is required.

extern API_FUNCTION
 NetAccessGetUserPerms(
  char FAR * pszServer,
  char FAR * pszUgName,
  char FAR * pszResource,
  unsigned short FAR * pusPerms
);

Parameters

pszServer
Pointer to a string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
pszUgName
Pointer to a string specifying the name of the user or group to query.
pszResource
Pointer to a string that contains the name of the network resource to query.
pusPerms
Pointer to an unsigned short integer that receives the user permissions for the specified resource.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmaccess.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Access Functions, NetAccessGetInfo, NetAccessEnum


NetAccessSetInfo

Windows 95/98/Me: The NetAccessSetInfo function changes the access-control list (ACL) for a resource.

Windows NT/2000 or later: The NetAccessSetInfo function is obsolete on Windows NT/Windows 2000. Win32-based applications should use the GetFileSecurity and SetFileSecurity functions.

Security Requirements

Requires Admin privilege to successfully execute on a computer that has local security enabled.

extern API_FUNCTION
 NetAccessSetInfo(
  const char FAR * pszServer,
  char FAR * pszResource,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short cbBuffer,
  short sParmNum
);

Parameters

pszServer
Pointer to a string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
pszResource
Pointer to a string that contains the name of the network resource to modify.
sLevel
Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
1 | The pbBuffer parameter points to an access_info_1 structure.

pbBuffer
Pointer to the buffer that contains the access information structure. The format of this data depends on the value of the sLevel parameter.
cbBuffer
Specifies the size, in bytes, of the buffer pointed to by the pbBuffer parameter.
sParmNum
This parameter must be equal to PARMNUM_ALL.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmaccess.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Access Functions, access_list, access_info_1, NetAccessGetInfo


NetAlertRaise

The NetAlertRaise function notifies all registered clients when a particular event occurs.

To simplify sending an alert message, you can call the extended function NetAlertRaiseEx instead. NetAlertRaiseEx does not require that you specify a STD_ALERT structure.

Security Requirements

No special group membership is required to successfully execute the NetAlertRaise function.

NET_API_STATUS NetAlertRaise(
  LPCWSTR AlertEventName,
  LPVOID Buffer,
  DWORD BufferSize
);

Parameters

AlertEventName
[in] Pointer to a constant Unicode string that specifies the alert class (type of alert) to raise. This parameter can be one of the following predefined values, or a user-defined alert class for network applications. (The event name for an alert can be any text string.)
Name | Meaning
ALERT_ADMIN_EVENT | An administrator's intervention is required.
ALERT_ERRORLOG_EVENT | An entry was added to the error log.
ALERT_MESSAGE_EVENT | A user or application received a broadcast message.
ALERT_PRINT_EVENT | A print job completed or a print error occurred.
ALERT_USER_EVENT | An application or resource was used.

Buffer
[in] Pointer to the data to send to the clients listening for the interrupting message. The data should begin with a fixed-length STD_ALERT structure followed by additional message data in one ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, or USER_OTHER_INFO structure. Finally, the buffer should include any required variable-length information. For more information, see the code sample in the following Remarks section.

The calling application must allocate and free the memory for all structures and variable data.

BufferSize
[in] Specifies the size of the message buffer, in bytes.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The alerter service must be running on the client computer when you call the NetAlertRaise function, or the function fails with ERROR_FILE_NOT_FOUND.

The following code sample demonstrates how to raise an administrative alert by calling the NetAlertRaise function and specifying STD_ALERT and ADMIN_OTHER_INFO structures. First, the sample calculates the size of the message buffer. Then it allocates the buffer with a call to the GlobalAlloc function. The code assigns values to the members of the STD_ALERT and the ADMIN_OTHER_INFO portions of the buffer. The sample retrieves a pointer to the ADMIN_OTHER_INFO structure by calling the ALERT_OTHER_INFO macro. It also retrieves a pointer to the variable data portion of the buffer by calling the ALERT_VAR_DATA macro. Finally, the code sample frees the memory allocated for the buffer with a call to the GlobalFree function.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <stdio.h>
#include <time.h>
#include <lm.h>

const int ALERT_VAR_DATA_SIZE = 216;

int wmain(int argc, wchar_t *argv[])
{
   int nBufferSize;
   LPVOID pAlertOtherInfo;
   PSTD_ALERT pStdAlert;              // STD_ALERT structure
   PADMIN_OTHER_INFO pAdminOtherInfo; // ADMIN_OTHER_INFO structure
   LPVOID pVarData;
   time_t now;
   DWORD dwResult;
   //
   // Check command line arguments.
   //
   if (argc != 2)
   {
      fwprintf(stderr, L"Usage: %s LogFileName\n", argv[0]);
      exit(1);
   }
   // Calculate the buffer size;
   //  then allocate the memory for the buffer.
   //
   nBufferSize  = sizeof(STD_ALERT) + ALERT_VAR_DATA_SIZE;
   pAlertOtherInfo = (LPVOID) GlobalAlloc(GPTR, nBufferSize);

   if (pAlertOtherInfo == NULL)
   {
       fwprintf(stderr, L"Unable to allocate memory\n");
       exit(1);
   }

   //
   // Assign values to the STD_ALERT portion of the buffer.
   //   (This is required when you call NetAlertRaise.)
   //
   pStdAlert = (PSTD_ALERT)pAlertOtherInfo;
   time( &now );
   pStdAlert->alrt_timestamp = (DWORD)now;
   wcscpy(pStdAlert->alrt_eventname, ALERT_ADMIN_EVENT);
   wcscpy(pStdAlert->alrt_servicename, argv[0]);
   //
   // Retrieve the pointer to the ADMIN_OTHER_INFO structure
   //  that follows the STD_ALERT portion of the buffer.
   /   Do this by calling the ALERT_OTHER_INFO macro.
   //
   pAdminOtherInfo = (PADMIN_OTHER_INFO)ALERT_OTHER_INFO(pAlertOtherInfo);
   //
   // Assign values to the ADMIN_OTHER_INFO structure.
   //
   pAdminOtherInfo->alrtad_numstrings = 1;
   //
   // Error 2377, NERR_LogOverflow, indicates
   //  a log file is full.
   //
   pAdminOtherInfo->alrtad_errcode = 2377;
   //
   // Retrieve the pointer to the variable data portion
   //  of the buffer by calling the ALERT_VAR_DATA macro.
   //
   pVarData = (LPTSTR)ALERT_VAR_DATA(pAdminOtherInfo);
   //
   // Supply the log file name for error 2377.
   //
   wcsncpy(pVarData,
           argv[1],
           ALERT_VAR_DATASIZE – (pVarData – pStdAlert) - 1);
   //
   // Send an administrative alert by calling the
   //  NetAlertRaise function.
   //
   dwResult = NetAlertRaise(ALERT_ADMIN_EVENT,
                            pAlertOtherInfo,
                            nBufferSize);
   //
   // Display the results of the function call.
   //
   if (dwResult != NERR_Success)
      wprintf(L"NetAlertRaise failed: %d\n", dwResult);
   else
      wprintf(L"Administrative alert raised successfully.\n");
   //
   // Free the allocated memory.
   //
   GlobalFree(pAlertOtherInfo);

   return (dwResult);
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Alert Functions, ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, NetAlertRaiseEx, PRINT_OTHER_INFO, STD_ALERT, USER_OTHER_INFO, ALERT_OTHER_INFO, ALERT_VAR_DATA


NetAlertRaiseEx

The NetAlertRaiseEx function notifies all registered clients when a particular event occurs. You can call this extended function to simplify the sending of an alert message because NetAlertRaiseEx does not require that you specify a STD_ALERT structure.

Security Requirements

No special group membership is required to successfully execute the NetAlertRaiseEx function.

NET_API_STATUS NetAlertRaiseEx(
  LPCWSTR AlertEventName,
  LPVOID VariableInfo,
  DWORD VariableInfoSize,
  LPCWSTR ServiceName
);

Parameters

AlertEventName
[in] Pointer to a constant Unicode string that specifies the alert class (type of alert) to raise. This parameter can be one of the following predefined values, or a user-defined alert class for network applications. (The event name for an alert can be any text string.)
Name | Meaning
ALERT_ADMIN_EVENT | An administrator's intervention is required.
ALERT_ERRORLOG_EVENT | An entry was added to the error log.
ALERT_MESSAGE_EVENT | A user or application received a broadcast message.
ALERT_PRINT_EVENT | A print job completed or a print error occurred.
ALERT_USER_EVENT | An application or resource was used.

VariableInfo
[in] Pointer to the data to send to the clients listening for the interrupting message. The data should consist of one ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, or USER_OTHER_INFO structure followed by any required variable-length information. For more information, see the code sample in the following Remarks section.

The calling application must allocate and free the memory for all structures and variable data.

VariableInfoSize
[in] Specifies the number of bytes of variable information in the buffer pointed to by the VariableInfo parameter.
ServiceName
[in] Pointer to a constant Unicode string that specifies the name of the service raising the interrupting message.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The alerter service must be running on the client computer when you call the NetAlertRaiseEx function, or the function fails with ERROR_FILE_NOT_FOUND.

The following code sample demonstrates how to raise the following three types of interrupting messages (alerts) by calling the NetAlertRaiseEx function:

  • An administrative alert by specifying an ADMIN_OTHER_INFO structure
  • A print alert by specifying a PRINT_OTHER_INFO structure
  • A user alert by specifying a USER_OTHER_INFO structure

In each instance the code assigns values to the members of the relevant alert information structure. Following this, the sample retrieves a pointer to the portion of the message buffer that follows the structure by calling the ALERT_VAR_DATA macro. The code also fills in the variable-length strings in this portion of the buffer. Finally, the sample calls NetAlertRaiseEx to send the alert.

Note that the calling application must allocate and free the memory for all structures and variable-length data in an alert message buffer.

Additional information about user alerts follows the code sample.

#ifndef UNICODE
#define UNICODE
#endif

#include <windows.h>
#include <lm.h>
#include <stdio.h>
#include <time.h>
//
// Define default strings.
//
#define PROGRAM_NAME    TEXT("NETALRT")
#define szComputerName  TEXT("\\\\TESTCOMPUTER")
#define szUserName      TEXT("TEST")
#define szQueueName     TEXT("PQUEUE")
#define szDestName      TEXT("MYPRINTER")
#define szStatus        TEXT("OK")
//
// Define structure sizes.
//
#define VAREDSIZE 312  // maximum size of the variable length message
char buff[VAREDSIZE];
//
int main()
{
   time_t             now;
   PADMIN_OTHER_INFO  pAdminInfo; // ADMIN_OTHER_INFO structure
   PPRINT_OTHER_INFO  pPrintInfo; // PRINT_OTHER_INFO structure
   PUSER_OTHER_INFO   pUserInfo;  // USER_OTHER_INFO structure
   TCHAR              *p;
   DWORD res;

   time( &now );  // Retrieve the current time to print it later.

   //
   // Sending an administrative alert
   //
   // Assign values to the members of the ADMIN_OTHER_INFO structure.
   //
   pAdminInfo = (PADMIN_OTHER_INFO) buff;
   ZeroMemory(pAdminInfo, VAREDSIZE);
   //
   // Error 2377, NERR_LogOverflow, indicates
   //  a log file is full.
   //
   pAdminInfo->alrtad_errcode = 2377;
   pAdminInfo->alrtad_numstrings = 1;
   //
   // Retrieve a pointer to the variable data portion at the
   //  end of the buffer by calling the ALERT_VAR_DATA macro.
   //
   p = (LPTSTR) ALERT_VAR_DATA(pAdminInfo);
   //
   // Fill in the variable-length, concatenated strings
   //  that follow the ADMIN_OTHER_INFO structure. These strings
   //  will be written to the message log.
   //
   lstrcpy(p,TEXT("'C:\\MYLOG.TXT'"));
   //
   // Call the NetAlertRaiseEx function to raise the
   //  administrative alert.
   //
   res = NetAlertRaiseEx(ALERT_ADMIN_EVENT, pAdminInfo, 255 , TEXT("MYSERVICE"));
   printf("Admin Alert: %u\n", res);

   //
   // Sending a print alert
   //
   // Assign values to the members of the PRINT_OTHER_INFO structure.
   //
   pPrintInfo = (PPRINT_OTHER_INFO) buff;
   ZeroMemory(pPrintInfo, VAREDSIZE);
   pPrintInfo->alrtpr_jobid = 5457;
   pPrintInfo->alrtpr_status = 0;
   pPrintInfo->alrtpr_submitted = now;
   pPrintInfo->alrtpr_size = 1000;
   //
   // Retrieve a pointer to the variable data portion at the
   //  end of the buffer by calling the ALERT_VAR_DATA macro.
   //
   p = (LPTSTR) ALERT_VAR_DATA(pPrintInfo);
   //
   // Fill in the variable-length, concatenated strings
   //  that follow the PRINT_OTHER_INFO structure.
   //
   lstrcpy(p, szComputerName); // computername
   p += lstrlen(p) + 1;
   lstrcpy(p, szUserName);     // username
   p += lstrlen(p) + 1;
   lstrcpy(p, szQueueName);    // printer queuename
   p += lstrlen(p) + 1;
   lstrcpy(p, szDestName);     // destination or printer name (optional)
   p += lstrlen(p) + 1;
   lstrcpy(p, szStatus);       // status of the print job (optional)
   //
   // Call the NetAlertRaiseEx function to raise the
   //  print alert.
   //
   res = NetAlertRaiseEx(ALERT_PRINT_EVENT, pPrintInfo, VAREDSIZE, TEXT("MYSERVICE"));
   printf("Print Alert: %u\n", res);

   //
   // Sending a user alert
   //
   // Assign values to the members of the USER_OTHER_INFO structure.
   //
   pUserInfo  = (PUSER_OTHER_INFO)  buff;
   ZeroMemory(pUserInfo, VAREDSIZE);
   pUserInfo->alrtus_errcode = -1;
   pUserInfo->alrtus_numstrings = 1;
   //
   // Retrieve a pointer to the variable data portion at the
   //  end of the buffer by calling the ALERT_VAR_DATA macro.
   //
   p = (LPTSTR) ALERT_VAR_DATA(pUserInfo);
   //
   // Fill in the variable-length, concatenated strings
   //  that follow the USER_OTHER_INFO structure.
   //
   lstrcpy(p,TEXT("C:\\USERLOG.TXT"));
   p += lstrlen(p) + 1;
   lstrcpy(p, szUserName);
   //
   // Call the NetAlertRaiseEx function to raise the
   //  user alert.
   //
   res = NetAlertRaiseEx(ALERT_USER_EVENT, pUserInfo, VAREDSIZE, TEXT("MYSERVICE"));
   printf("User  Alert: %u\n", res);

   return(res);
}

To pass a user-defined structure and valid strings in a user alert, you must create an event message file and link it with your application. You must also register the application in the EventMessageFile subkey in the EventLog section of the registry. If you do not register the application, the user alert will contain the information you pass in the variable-length strings that follow the USER_OTHER_INFO structure. For more information about the EventMessageFile registry value, see Event Logging.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Alert Functions, NetAlertRaise, ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, USER_OTHER_INFO, ALERT_VAR_DATA


NetApiBufferAllocate

The NetApiBufferAllocate function allocates memory from the heap. Use this function only when compatibility with the NetApiBufferFree function is required. Otherwise, use the memory management functions.

NET_API_STATUS NetApiBufferAllocate(
  DWORD ByteCount,
  LPVOID *Buffer
);

Parameters

ByteCount
[in] Specifies the number of bytes to allocate.
Buffer
[out] Receives a pointer to the allocated buffer.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The following code sample demonstrates how to use the network management ApiBuffer functions.

The sample first calls the NetApiBufferAllocate function to allocate memory and then the NetApiBufferSize function to retrieve the size of the allocated memory. Following this, the sample calls NetApiBufferReallocate to change the size of the memory allocation. Finally, the sample calls NetApiBufferFree to free the memory. In each case, the sample prints a message indicating success or failure.

#define UNICODE
#include <windows.h>
#include <lm.h>
#include <stdio.h>

void PrintError(LPSTR lpszApi, DWORD res);

int main()
{
   PUSER_INFO_10 p;
   DWORD res, dwSize;

   // Call the NetApiBufferAllocate function
   //   to allocate the memory. If successful,
   //   print a message.
   //
   res = NetApiBufferAllocate(1024, (LPVOID *) &p);
   if(res == NERR_Success)
   {
      printf("NetApiBufferAllocate:   Allocated 1024 bytes.\n");

      // Call the NetApiBufferSize function
      //   to retrieve the size of the allocated buffer.
      //   If successful, print the size.
      //
      res = NetApiBufferSize(p, &dwSize);
      if(res == NERR_Success)
      {
         printf("NetApiBufferSize:       Buffer has %u bytes.\n", dwSize);

         // Call the NetApiBufferReallocate function
         //   to change the size of the allocated memory.
         //   If successful, print the new size of the buffer.
         //
         res = NetApiBufferReallocate(p, dwSize * 2, (LPVOID *) &p);
         if(res == NERR_Success)
            printf("NetApiBufferReallocate: Re-Allocated %u bytes.\n", dwSize * 2);
         else
            PrintError("NetApiBufferReallocate", res);

         // Call the NetApiBufferFree function
         //    to free the allocated memory.
         //    If successful, print a message.
         //
         res = NetApiBufferFree(p);
         if(res == NERR_Success)
            printf("Freed Buffer\n");

         else
            PrintError("NetApiBufferFree", res);
      }
      else
         PrintError("NetApiBufferSize", res);
   }
   else
      PrintError("NetApiBufferAllocate", res);
   return 0;
}

void PrintError(LPSTR lpszApi, DWORD res)
{
   printf("%s: Error %u\n", lpszApi, res);
   return;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmapibuf.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Api Buffer Functions, NetApiBufferFree, NetApiBufferReallocate


NetApiBufferFree

The NetApiBufferFree function frees the memory that the NetApiBufferAllocate function allocates. Call NetApiBufferFree to free the memory that other network management functions return on Windows NT/Windows 2000.

NET_API_STATUS NetApiBufferFree(
  LPVOID Buffer
);

Parameters

Buffer
[in] Pointer to a buffer returned previously by another network management function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

For a code sample that demonstrates how to use the network management ApiBuffer functions, see NetApiBufferAllocate.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmapibuf.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Api Buffer Functions, NetApiBufferAllocate, NetApiBufferReallocate


NetApiBufferReallocate

The NetApiBufferReallocate function changes the size of a buffer allocated by a previous call to the NetApiBufferAllocate function.

NET_API_STATUS NetApiBufferReallocate(
  LPVOID OldBuffer,
  DWORD NewByteCount,
  LPVOID *NewBuffer
);

Parameters

OldBuffer
[in] Pointer to the buffer returned by a call to the NetApiBufferAllocate function.
NewByteCount
[in] Specifies the new size of the buffer, in bytes.
NewBuffer
[out] Receives the pointer to the reallocated buffer.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

For a code sample that demonstrates how to use the network management ApiBuffer functions, see NetApiBufferAllocate.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmapibuf.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Api Buffer Functions, NetApiBufferAllocate, NetApiBufferFree


NetApiBufferSize

The NetApiBufferSize function returns the size, in bytes, of a buffer allocated by a call to the NetApiBufferAllocate function.

NET_API_STATUS NetApiBufferSize(
  LPVOID Buffer,
  LPDWORD ByteCount
);

Parameters

Buffer
[in] Pointer to a buffer returned by the NetApiBufferAllocate function.
ByteCount
[out] Receives the size of the buffer, in bytes.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

For a code sample that demonstrates how to use the network management ApiBuffer functions, see NetApiBufferAllocate.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmapibuf.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Api Buffer Functions, NetApiBufferAllocate, NetApiBufferFree


NetAuditClear

The NetAuditClear function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaudit.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetAuditRead

The NetAuditRead function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaudit.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetAuditWrite

The NetAuditWrite function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaudit.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetConfigGet

The NetConfigGet function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmconfig.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetConfigGetAll

The NetConfigGetAll function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmconfig.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetConfigSet

The NetConfigSet function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the registry.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmconfig.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetConnectionEnum

The NetConnectionEnum function lists all connections made to a shared resource on the server or all connections established from a particular computer. If there is more than one user using this connection, then it is possible to get more than one structure for the same connection, but with a different user name.

Security Requirements

Admin or server, print, or comm operator group membership is required to successfully execute the NetConnectionEnum function.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetConnectionEnum(
  LPWSTR servername,
  LPWSTR qualifier,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Windows 95/98/Me: The calling application must use the cbBuffer parameter to specify the size, in bytes, of the information buffer pointed to by the pbBuffer parameter. (The cbBuffer parameter replaces the Windows NT/Windows 2000 prefmaxlen parameter.) A resume handle parameter is not available on this platform. Therefore, the parameter list is as follows.

extern API_FUNCTION
 NetConnectionEnum(
  const char FAR *pszServer,
  const char FAR *pszQualifier,
  short sLevel,
  char FAR *pbBuffer,
  unsigned short  cbBuffer,
  unsigned short FAR *pcEntriesRead,
  unsigned short FAR *pcTotalAvail
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
qualifier
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying a share name or computer name for the connections of interest. If it is a share name, then all the connections made to that share name are listed. If it is a computer name (for example, it starts with two backslash characters), then NetConnectionEnum lists all connections made from that computer to the server specified.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Windows NT/2000 or later: Return connection identifiers. The bufptr parameter is a pointer to an array of CONNECTION_INFO_0 structures.
1 | Windows NT/2000 or later: Return connection identifiers and connection information. The bufptr parameter is a pointer to an array of CONNECTION_INFO_1 structures.
50 | Windows 95/98/Me: Return connection information. The pbBuffer parameter is a pointer to an array of connection_info_50 structures.

bufptr
[out] Pointer to the address of the buffer that receives the information. The format of this data depends on the value of the level parameter.

Windows NT/2000 or later: This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

Windows 95/98/Me: The caller must allocate and deallocate this buffer.

prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a value that receives the total number of entries that could have been enumerated from the current resume position.
resume_handle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing connection search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Windows 95/98/Me: See the NetConnectionEnum Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetConnectionEnum function.

Windows NT/2000 or later: The following code sample demonstrates how to list the connections made to a shared resource with a call to the NetConnectionEnum function. The sample calls NetConnectionEnum, specifying information level 1 (CONNECTION_INFO_1). If there are entries to return, it prints the values of the coni1_username and coni1_netname members. If there are no entries to return, the sample prints an appropriate message. Finally, the code sample frees the memory allocated for the information buffer.

#define UNICODE
#include <windows.h>
#include <lm.h>
#include <stdio.h>

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res, i, er = 0, tr = 0, resume = 0;
   PCONNECTION_INFO_1 p,b;
   LPTSTR lpszServer = NULL, lpszShare = NULL;

   if(argc<2)
      wprintf(L"Syntax: %s [ServerName] ShareName | \\\\ComputerName\n", argv[0]);
   else
   {
      //
      // The server is not the default local computer.
      //
      if(argc>2)
         lpszServer=argv[1];
      //
      // ShareName is always the last argument.
      //
      lpszShare=argv[argc - 1];
      //
      // Call the NetConnectionEnum function,
      //  specifying information level 1.
      //
      res=NetConnectionEnum(lpszServer, lpszShare, 1, (LPBYTE *) &p, -1, &er, &tr, &resume);
      //
      // If no error occurred,
      //
      if(res == 0)
      {
         //
         // If there were any results,
         //
         if(er>0)
         {
            b=p;
            //
            // Loop through the entries; print username and netname.
            //
            for(i=0;i<er;i++)
            {
               printf("%S\t%S\n", b->coni1_username,b->coni1_netname);
               b++;
            }
            // Free the allocated buffer.
            //
            NetApiBufferFree(p);
         }
         // Otherwise, print a message depending on whether
         //  the qualifier parameter was a computer (\\ComputerName)
         //  or a share (ShareName).
         //
         else
         {
            if(lpszShare[0]=='\\')
               printf("No connection to %S from %S\n",
                  (lpszServer == NULL)?TEXT("LocalMachine"):lpszServer, lpszShare);
            else
               printf("No one connected to %S\\%S\n",
                  (lpszServer == NULL)?TEXT("\\\\LocalMachine"):lpszServer,lpszShare);
         }
      }
      //
      // Otherwise, print the error.
      //
      else
         printf("Error: %d\n",res);
   }
   return;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Share Functions, CONNECTION_INFO_0, CONNECTION_INFO_1, connection_info_50


NetDfsAdd

The NetDfsAdd function creates a new Distributed File System (Dfs) link or adds shares to an existing link in a Dfs root.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsAdd function.

NET_API_STATUS NetDfsAdd(
  LPWSTR DfsEntryPath,   // Dfs entry path for added Dfs link
  LPWSTR ServerName,     // name of server exporting the storage
  LPWSTR ShareName,      // existing share name for the storage
  LPWSTR Comment,        // optional comment for the Dfs link
  DWORD Flags            // zero for no flags
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link in a named Dfs root. The string must be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share that is published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that the Dfs link references. The string must begin with \\.
ShareName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server that the Dfs link references.
Comment
[in] Pointer to a null-terminated Unicode character string that specifies an optional comment associated with the Dfs link.
Flags
[in] Specifies a DWORD value that contains a set of bit flags defining various options. This parameter can be one or more of the following values, or you can specify zero for no flags. If you specify zero, the function adds a new replica to an existing Dfs link. If you do not set the DFS_ADD_VOLUME flag, the function also attempts to add a new replica to an existing Dfs link.
Value | Meaning
DFS_ADD_VOLUME | Create a new Dfs link. If the Dfs link already exists, the NetDfsAdd function fails. Dfs attempts to verify the existence of the share specified by the ShareName parameter when you specify this flag. For more information, see the following Remarks section.
DFS_RESTORE_VOLUME | Create a new Dfs link, but do not check for the existence of the share specified by the ShareName parameter. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

When you specify DFS_ADD_VOLUME, Dfs attempts to check for the existence of the share specified by the ShareName parameter. If the server specified by the ServerName parameter exists, but the specified share does not exist, the NetDfsAdd function fails. NetDfsAdd does not return an error in situations when Dfs cannot contact the specified server.

The DFS_RESTORE_VOLUME value is intended primarily for use during restoration of a Dfs root. If you set the Flags parameter to DFS_RESTORE_VOLUME, when the Dfs service is creating Dfs links it does not verify whether the ServerName and ShareName parameters contain valid references. This is useful in the case when a server or computer that is the target of a Dfs link is offline or unavailable at the time of Dfs root restoration.

The following code sample demonstrates how to create a new Dfs link using a call to the NetDfsAdd function. Because the sample specifies the value DFS_ADD_VOLUME in the Flags parameter, the call to NetDfsAdd fails if the Dfs link already exists. To add additional storage to an existing Dfs link, you can specify zero in the Flags parameter.

#define UNICODE
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res;
   LPTSTR lpszComment;
   lpszComment = argc < 5 ? NULL : argv[4];
   //
   // Check for required parameters.
   //
   if (argc<4)
      wprintf(L"Syntax: %s DfsEntryPath ServerName ShareName [\"Comment\"]\n", argv[0]);
   else
   {
      //
      // Call the NetDfsAdd function; fail the call
      //  if the Dfs link already exists (DFS_ADD_VOLUME).
      // To add a second storage to a Dfs link, change
      //  the last parameter to 0.
      //
      res = NetDfsAdd(argv[1], argv[2], argv[3], argv[4], DFS_ADD_VOLUME);
      //
      // If the call succeeds,
      //
      if(res==0)
         printf("Added Dfs link\n");
      else
         printf("Error: %u\n", res);
   }
   return;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, NetDfsEnum, NetDfsRemove, NetDfsAddStdRoot, NetDfsAddFtRoot


NetDfsAddFtRoot

The NetDfsAddFtRoot function creates the root of a new domain-based Distributed File System (Dfs) implementation. If the root already exists, the function adds (joins) the specified server and share to the root.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

Users having permission to update the Dfs container in the directory service can successfully execute the NetDfsAddFtRoot function.

NET_API_STATUS NetDfsAddFtRoot(
  LPWSTR ServerName,
  LPWSTR RootShare,
  LPWSTR FtDfsName,
  LPWSTR Comment,
  DWORD Flags
);

Parameters

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that will host the root of the new domain-based Dfs implementation. The string must begin with \\. If the root already exists, this parameter specifies the name of a server to add to the existing root. This parameter is required.
RootShare
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that will host the root of the new domain-based Dfs implementation. If the root already exists, this parameter specifies the name of a share to add to the existing root. This parameter is required.
FtDfsName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the root to create or join to the domain-based Dfs. This parameter is required.
Comment
[in] Pointer to a null-terminated Unicode character string that contains an optional comment associated with the Dfs link.
Flags
[in] Must be zero.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, NetDfsRemoveFtRoot, NetDfsAdd


NetDfsAddStdRoot

The NetDfsAddStdRoot function creates the root for a new stand-alone Distributed File System (Dfs) implementation.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsAddStdRoot function.

NET_API_STATUS NetDfsAddStdRoot(
  LPWSTR ServerName,
  LPWSTR RootShare,
  LPWSTR Comment,
  DWORD Flags
);

Parameters

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that will host the root of the new stand-alone Dfs implementation. The string must begin with \\. This parameter is required.
RootShare
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that will host the new Dfs root. This parameter is required.
Comment
[in, optional] Pointer to a null-terminated Unicode character string that contains an optional comment associated with the Dfs link.
Flags
[in] Must be zero.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, NetDfsRemoveStdRoot, NetDfsAddFtRoot, NetDfsAdd


NetDfsAddStdRootForced

The NetDfsAddStdRootForced function creates the root for a new stand-alone Distributed File System (Dfs) implementation in a cluster technology environment, allowing an offline share to host the Dfs root.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsAddStdRootForced function.

NET_API_STATUS NetDfsAddStdRootForced(
  LPWSTR ServerName,
  LPWSTR RootShare,
  LPWSTR Comment,
  LPWSTR Store
);

Parameters

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that will host the root of the new stand-alone Dfs implementation. The string must begin with \\. This parameter is required.
RootShare
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that will host the new Dfs root. This parameter is required.
Comment
[in, optional] Pointer to a null-terminated Unicode character string that contains an optional comment associated with the Dfs link.
Store
[in] Pointer to a null-terminated Unicode character string that specifies the path to the share that will host the new Dfs root. This parameter is required and must be of the form:
drive:\directory

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The NetDfsAddStdRootForced function exists only for clustering technology. It is recommended that you use the function only if you are thoroughly familiar with the concepts and architecture of Dfs.

Under normal circumstances, you can create the root for a new stand-alone Dfs implementation by calling the NetDfsAddStdRoot function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, NetDfsAddStdRoot, NetDfsRemoveStdRoot


NetDfsEnum

The NetDfsEnum function enumerates all the Distributed File System (Dfs) links in the named Dfs root. The function returns information about the Dfs links based on information specified by the Level parameter.

Security Requirements

No special group membership is required to successfully execute the NetDfsEnum function.

NET_API_STATUS NetDfsEnum(
  LPWSTR DfsName,        // name of the Dfs for enumeration
  DWORD Level,           // level of information requested
  DWORD PrefMaxLen,      // advisory, but -1 means return
                         //  all information
  LPBYTE *Buffer,        // function allocates and returns the
                         //  buffer with requested info
  LPDWORD EntriesRead,   // number of entries returned
  LPDWORD ResumeHandle   // must be 0 on first call, reused
                         //  on subsequent calls
);

Parameters

DfsName
[in] Pointer to a null-terminated Unicode character string that specifies the name of a Windows NT/Windows 2000 server that hosts the Dfs root. The string must begin with \\.
Level
[in] Specifies the information level of the request. This parameter can be one of the following values.
Value | Meaning
1 | Return Dfs link names. The Buffer parameter points to an array of DFS_INFO_1 structures.
2 | Return Dfs link names and additional information. The Buffer parameter points to an array of DFS_INFO_2 structures.
3 | Return Dfs link information and share information. The Buffer parameter points to an array of DFS_INFO_3 structures.
4 | Return Dfs link information, share information, and storage-specific information. The Buffer parameter points to an array of DFS_INFO_4 structures.
200 | Return the name associated with the root of a domain-based Dfs implementation. The Buffer parameter points to an array of DFS_INFO_200 structures.

PrefMaxLen
[in] Specifies the preferred maximum number of bytes that should be returned by this enumeration function call in the information structure buffer. If this parameter is MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. For more information, see the following Remarks section.
Buffer
[out] Pointer to the address of a buffer that receives the requested information structures. The format of this data depends on the value of the Level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.
EntriesRead
[out] Pointer to a DWORD value that receives the actual enumerated Dfs link count.
ResumeHandle
[in/out] Pointer to a DWORD value that contains a handle which is used to continue the enumeration. The handle should be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Call the NetDfsEnum function with the ResumeHandle parameter set to zero to begin the enumeration. To retrieve information about additional Dfs links, call the function with the ResumeHandle returned by the previous call to NetDfsEnum.

The NetDfsEnum function allocates the memory required for the information structure buffer. If you specify an amount in the PrefMaxLen parameter, it restricts the number of bytes that the function returns. However, the actual size of the memory that the NetDfsEnum function allocates can be greater than the amount you specify. For additional information see Network Management Function Buffer Lengths.

You can use the PrefMaxLen value for performance tuning. For example, if you call the function to fill a list box, and the list box can hold only 10 entries, a reasonable value for PrefMaxLen might be 12 * sizeof(DFS_INFO_n).

The following code sample demonstrates how to list the Dfs links in a named Dfs root with a call to the NetDfsEnum function. The sample calls NetDfsEnum, specifying information level 3 (DFS_INFO_3). The sample code loops through the entries and prints the retrieved data and the status of each storage server referenced by the Dfs link. Finally, the sample frees the memory allocated for the information buffer.

#define UNICODE
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>

void wmain(int argc, wchar_t *argv[ ])
{
   PDFS_INFO_3 pData, p;
   PDFS_STORAGE_INFO ps;
   DWORD er=0, tr=0, res, i, j;

   if(argc<2)
      wprintf(L"Syntax: %s \\\\DfsName\n", argv[0]);
   else
   {
      //
      // Call the NetDfsEnum function, specifying level 3.
      //
      res = NetDfsEnum(argv[1], 3, 0xFFFFFFFF, (LPBYTE *) &pData, &er, &tr);
      //
      // If no error occurred,
      //
      if(res==0)
      {
         p=pData;
         //
         // Loop through the entries; print the data.
         //
         for(i=1;i<=er;i++)
         {
            printf("%-30S%u\n",p->EntryPath, p->NumberOfStorages);
            ps = p->Storage;
            //
            // Loop through each storage.
            //
            for(j=1;j<=p->NumberOfStorages;j++)
            {
               //
               // Print the status (Offline/Online) and the name
               //  of each storage referenced by the Dfs link.
               //
               printf("    %S  ", (ps->State == DFS_STORAGE_STATE_OFFLINE) ? TEXT("Offline"):TEXT("Online "));
               printf("\\\\%S\\%S\n",ps->ServerName,ps->ShareName);
               ps++;
            }
            p++;
         }
         // Free the allocated buffer.
         //
         NetApiBufferFree(pData);
      }
      //
      // Otherwise, print the error.
      //
      else
         printf("Error: %u\n", res);
   }
   return;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, DFS_INFO_1, DFS_INFO_2, DFS_INFO_3, DFS_INFO_4, DFS_INFO_200, NetDfsAdd, NetDfsRemove


NetDfsGetClientInfo

The NetDfsGetClientInfo function retrieves information about a Distributed File System (Dfs) link in the named Dfs root. The information represents the current computer's cached copy of the information about the Dfs link.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

No special group membership is required to successfully execute the NetDfsGetClientInfo function.

NET_API_STATUS NET_API_FUNCTION NetDfsGetClientInfo(
  LPWSTR DfsEntryPath,  // Dfs entry path for the junction point
  LPWSTR ServerName,    // name of server exporting the storage
  LPWSTR ShareName,     // name of share exporting the storage
  DWORD Level,          // level of information requested
  LPBYTE *Buffer        // receives requested information
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link in a named Dfs root. The string must be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the host server that the Dfs link references. The string must begin with \\. This parameter is optional.
ShareName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server that the Dfs link references. This parameter is optional.
Level
[in] Specifies the information level of the request. This parameter can be one of the following values.
Value | Meaning
1 | Return the Dfs link name. The Buffer parameter points to a DFS_INFO_1 structure.
2 | Return the Dfs link name and additional information. The Buffer parameter points to a DFS_INFO_2 structure.
3 | Return Dfs link information and share information. The Buffer parameter points to a DFS_INFO_3 structure.
4 | Return Dfs link information, share information, and storage-specific information. The Buffer parameter points to a DFS_INFO_4 structure.

Buffer
[out] Pointer to the address of a buffer that receives the requested information. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, DFS_INFO_1, DFS_INFO_2, DFS_INFO_3, DFS_INFO_4, NetDfsSetClientInfo


NetDfsGetInfo

The NetDfsGetInfo function retrieves information about a Distributed File System (Dfs) link in the named Dfs root. The function can return information specific to a server and share, or information specific to an entire Dfs link.

Security Requirements

No special group membership is required to successfully execute the NetDfsGetInfo function.

NET_API_STATUS NetDfsGetInfo(
  LPWSTR DfsEntryPath, // Dfs entry path for the Dfs link
  LPWSTR ServerName,   // name of server exporting the storage
  LPWSTR ShareName,    // name of share exporting the storage
  DWORD Level,         // level of information requested
  LPBYTE *Buffer       // function allocates and returns
                       //  buffer with requested info
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link in a named Dfs root. The string must be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

ServerName
[in, optional] Pointer to a null-terminated Unicode character string that specifies the name of the host server that the Dfs link references. The string must begin with \\. This parameter is optional. For additional information, see the following Remarks section.
ShareName
[in, optional] Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server that the Dfs link references. This parameter is optional. For additional information, see the following Remarks section.
Level
[in] Specifies the information level of the request. This parameter can be one of the following values.
Value | Meaning
1 | Return the Dfs link name. The Buffer parameter points to a DFS_INFO_1 structure.
2 | Return the Dfs link name and additional information. The Buffer parameter points to a DFS_INFO_2 structure.
3 | Return Dfs link information and share information. The Buffer parameter points to a DFS_INFO_3 structure. If you specify this information level, the function ignores the ServerName and ShareName parameters and returns information for the entire Dfs link.
4 | Return Dfs link information, share information, and storage-specific information. The Buffer parameter points to a DFS_INFO_4 structure.
100 | Return a comment about the Dfs link. The Buffer parameter points to a DFS_INFO_100 structure.

Buffer
[out] Pointer to the address of a buffer that receives the requested information structures. The format of this data depends on the value of the Level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

If you specify both the ServerName and ShareName parameters, the NetDfsGetInfo function returns information specific to that server and share. If the parameters are not specified, the function returns information that is specific to the entire Dfs link.

The following code sample demonstrates how to retrieve information about a Dfs link using a call to the NetDfsGetInfo function. The sample calls NetDfsGetInfo, specifying information level 3 (DFS_INFO_3). If the call succeeds, the sample prints information about the Dfs link, including the name and status of each share referenced by the link. Finally, the code sample frees the memory allocated for the information buffer.

#define UNICODE
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>

void wmain(int argc, wchar_t *argv[ ])
{
   PDFS_INFO_3 pData;
   PDFS_STORAGE_INFO ps;
   DWORD er=0, tr=0, res, j;

   LPTSTR lpszServer, lpszShare;
   //
   // Check command line arguments.
   //
   lpszShare = argc < 4 ? NULL : argv[3];
   lpszServer = argc < 3 ? NULL : argv[2];
   if (argc<2)
      wprintf(L"Syntax: %s DfsEntryPath [ServerName ShareName]\n", argv[0]);
   else
   {
      //
      // Call the NetDfsGetInfo function, specifying level 3.
      //
      res = NetDfsGetInfo(argv[1], lpszServer, lpszShare, 3, (LPBYTE *) &pData);
      //
      // If the call succeeds, print the data.
      //
      if(res==0)
      {
         printf("%-30S Storages: %u\nComment: %S\n",pData->EntryPath, pData->NumberOfStorages, pData->Comment);
         ps = pData->Storage;
         //
         // Loop through each storage.
         //
         for(j=1;j<=pData->NumberOfStorages;j++)
         {
            //
            // Print the status (Offline/Online) and the name
            //  of each storage referenced by the Dfs link.
            //
            printf("    %S  ", (ps->State == DFS_STORAGE_STATE_OFFLINE) ? TEXT("Offline"): TEXT("Online "));
            printf("\\\\%S\\%S\n",ps->ServerName,ps->ShareName);
            ps++;
         }
         //
         // Free the allocated memory.
         //
         NetApiBufferFree(pData);
      }
      else
         printf("Error: %u\n", res);
   }
   return;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, DFS_INFO_1, DFS_INFO_2, DFS_INFO_3, DFS_INFO_4, DFS_INFO_100, NetDfsEnum


NetDfsManagerInitialize

The NetDfsManagerInitialize function reinitializes the Dfs service (dfssvc.exe) on the specified server.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsManagerInitialize function.

NET_API_STATUS NetDfsManagerInitialize(
  LPWSTR ServerName,
  DWORD Flags
);

Parameters

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the host server that requires reinitialization of the Dfs service. The string must begin with \\. This parameter is required.
Flags
[in] Must be zero.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

It is recommended that you call the NetDfsManagerInitialize function only if you are thoroughly familiar with the concepts and architecture of Dfs. The function performs the equivalent of a net stop dfs command followed by a net start dfs command.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions


NetDfsRemove

The NetDfsRemove function removes a server share from a Distributed File System (Dfs) link. If the specified share is the last share associated with the Dfs link, then the NetDfsRemove function also removes the link.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsRemove function.

NET_API_STATUS NetDfsRemove(
  LPWSTR DfsEntryPath, // Dfs entry path for the junction point
  LPWSTR ServerName,   // name of server exporting the storage
  LPWSTR ShareName     // name of share exporting the storage
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link in a named Dfs root. The string must be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the host server that the Dfs link references. The string must begin with \\.
ShareName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server that the Dfs link references.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The following code sample demonstrates how to remove a server share from a Dfs link using a call to the NetDfsRemove function.

#define UNICODE
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>

void wmain(int argc, wchar_t *argv[ ])
{
   DWORD res;
   //
   // All parameters are required.
   //
   if (argc<4)
      wprintf(L"Syntax: %s DfsEntryPath ServerName ShareName\n", argv[0]);
   else
   {
      //
      // Call the NetDfsRemove function
      //  to remove the Dfs link.
      //
      res = NetDfsRemove(argv[1], argv[2], argv[3]);
      //
      // Display the result of the call.
      //
      if(res==0)
         printf("Removed Dfs link\n");
      else
         printf("Error: %u\n", res);
   }
   return;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, NetDfsAdd, NetDfsEnum, NetDfsRemoveStdRoot, NetDfsRemoveFtRoot


NetDfsRemoveFtRoot

The NetDfsRemoveFtRoot function removes the specified server and share from a domain-based Distributed File System (Dfs) root. If the share is the last associated with the Dfs root, the function also deletes the root.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

Users having permission to update the Dfs container in the directory service can successfully execute the NetDfsRemoveFtRoot function.

NET_API_STATUS NetDfsRemoveFtRoot(
  LPWSTR ServerName,
  LPWSTR RootShare,
  LPWSTR FtDfsName,
  DWORD Flags
);

Parameters

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server to remove. The string must begin with \\. The server must host the root of a domain-based Dfs implementation. This parameter is required.
RootShare
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share to remove. This parameter is required.
FtDfsName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the domain-based Dfs root from which to remove the server and share. This parameter is required.
Flags
[in] Must be zero.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, NetDfsAddFtRoot, NetDfsRemoveFtRootForced, NetDfsRemove


NetDfsRemoveFtRootForced

The NetDfsRemoveFtRootForced function removes the specified server and share from a domain-based Distributed File System (Dfs) root, even if the server is offline. If the share is the last associated with the Dfs root, the function also deletes the root.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

Users having permission to update the Dfs container in the directory service can successfully execute the NetDfsRemoveFtRootForced function.

Note The NetDfsRemoveFtRootForced function does not update the registry on the domain-based Dfs host server. This function should be used only when the domain-based Dfs root is unavailable. For more information, see the following Remarks section.

NET_API_STATUS NetDfsRemoveFtRootForced(
  LPWSTR DomainName,
  LPWSTR ServerName,
  LPWSTR RootShare,
  LPWSTR FtDfsName,
  DWORD Flags
);

Parameters

DomainName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the domain that contains the domain-based Dfs root to remove. This parameter is required.
ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server that hosts the root of the domain-based Dfs implementation. The string must begin with \\. This parameter is required.
RootShare
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the storage server that hosts the root of the domain-based Dfs implementation. This parameter is required.
FtDfsName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the domain-based Dfs root from which to remove the server and share. This parameter is required.
Flags
[in] Must be zero.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

It is recommended that you call the NetDfsRemoveFtRootForced function only if you are thoroughly familiar with the concepts and architecture of domain-based Dfs. The function does not update the server with the new Dfs root.

Because NetDfsRemoveFtRootForced does not update the registry, the function should be used only when the domain-based Dfs root is unavailable. Under normal circumstances, you can remove the server and share from a domain-based Dfs by calling the NetDfsRemoveFtRoot function.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, NetDfsRemoveFtRoot, NetDfsAddFtRoot


NetDfsRemoveStdRoot

The NetDfsRemoveStdRoot function removes the server and share at the root of a stand-alone Distributed File System (Dfs) implementation.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsRemoveStdRoot function.

NET_API_STATUS NetDfsRemoveStdRoot(
  LPWSTR ServerName,
  LPWSTR RootShare,
  DWORD Flags
);

Parameters

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the storage server to remove. The server must host the root of a Dfs implementation, and the string must begin with \\. This parameter is required.
RootShare
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server to remove. This parameter is required.
Flags
[in] Must be zero.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, NetDfsAddStdRoot, NetDfsRemoveFtRoot, NetDfsRemove


NetDfsSetClientInfo

The NetDfsSetClientInfo function associates information with a Distributed File System (Dfs) link in the named Dfs root. The information represents the current computer's cached copy of the information about the Dfs link. Only the cached information is changed. The link time-out, active machine/share, and machine/share availability may be set.

Note This function is currently being evaluated and may or may not be supported in future versions.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsSetClientInfo function.

NET_API_STATUS NET_API_FUNCTION NetDfsSetClientInfo(
  LPWSTR DfsEntryPath,  // Dfs entry path for the junction point
  LPWSTR ServerName,    // name of server exporting the storage
  LPWSTR ShareName,     // name of share exporting the storage
  DWORD Level,          // level of information to set
  LPBYTE Buffer         // buffer holding information
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link. The string must be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the host server that the Dfs link references. The string must begin with \\. This parameter is optional. For additional information, see the following Remarks section.
ShareName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server that the Dfs link references. This parameter is optional. For additional information, see the following Remarks section.
Level
[in] Specifies the information level of the request. This parameter can be one of the following values.
Value | Meaning
101 | Set the local Dfs link's storage status. The Buffer parameter points to a DFS_INFO_101 structure.
102 | Set the local Dfs link time-out. The Buffer parameter points to a DFS_INFO_102 structure. For more information, see the following Remarks section.
Buffer
[in] Pointer to a buffer that specifies the data. The format of this data depends on the value of the Level parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Setting the time-out to zero may not immediately delete the local cached copy of the Dfs link, because threads may be referencing the entry.

Because there is only one time-out on a Dfs link, the ServerName and ShareName parameters are ignored for level 102.

The DFS_STORAGE_STATE_ONLINE and DFS_STORAGE_STATE_OFFLINE bits will be ignored. The DFS_STORAGE_STATE_ACTIVE bit is valid only if no files are open to the active machine/share.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, DFS_INFO_101, DFS_INFO_102, NetDfsGetClientInfo


NetDfsSetInfo

The NetDfsSetInfo function associates information with a Distributed File System (Dfs) link in the named Dfs root. The function can set information relevant to a specific server and share, or information specific to an entire Dfs link.

Security Requirements

Administrator privileges are required to successfully execute the NetDfsSetInfo function.

NET_API_STATUS NetDfsSetInfo(
  LPWSTR DfsEntryPath,  // Dfs entry path for the Dfs link
  LPWSTR ServerName,    // name of server exporting the storage
  LPWSTR ShareName,     // name of share exporting the storage
  DWORD Level,          // level of information to be set
  LPBYTE Buffer         // buffer holding information
);

Parameters

DfsEntryPath
[in] Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link. The string must be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

ServerName
[in, optional] Pointer to a null-terminated Unicode character string that specifies the name of the host server that the Dfs link references. The string must begin with \\. This parameter is optional. For additional information, see the following Remarks section.
ShareName
[in, optional] Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server that the Dfs link references. This parameter is optional. For additional information, see the following Remarks section.
Level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
100 | Set the comment associated with the Dfs link. The Buffer parameter points to a DFS_INFO_100 structure.
101 | Set the storage state associated with the Dfs link. The Buffer parameter points to a DFS_INFO_101 structure.
102 | Set the time-out value associated with the Dfs link. The Buffer parameter points to a DFS_INFO_102 structure.

Buffer
[in] Pointer to a buffer that specifies the data. The format of this data depends on the value of the Level parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

If you specify both the ServerName and ShareName parameters, the NetDfsSetInfo function returns information specific to that server and share. If the parameters are not specified, the function returns information that is specific to the entire Dfs link.

The following code sample demonstrates how to associate a comment with a Dfs link using a call to the NetDfsSetInfo function. The sample specifies information level 100 (DFS_INFO_100).

#define UNICODE
#include <windows.h>
#include <lm.h>
#include <lmdfs.h>
#include <stdio.h>

void wmain(int argc, wchar_t *argv[ ])
{
   DFS_INFO_100 dfsData;
   DWORD res;
   //
   // Check command line arguments.
   //
   if (argc<2)
      wprintf(L"Syntax: %s DfsEntryPath [\"Comment\"]\n", argv[0]);
   else
   {
      //
      // Fill in DFS_INFO_100 structure member.
      //
      dfsData.Comment = argc < 3 ? NULL : argv[2];
      //
      // Call the NetDfsSetInfo function, specifying level 100.
      //
      res=NetDfsSetInfo(argv[1], NULL, NULL, 100, (LPBYTE) &dfsData);
      //
      // Display the result of the call.
      //
      if(res == 0)
         printf("Comment set.\n");
      else
         printf("Error: %u", res);
   }
   return;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Distributed File System (Dfs) Functions, DFS_INFO_100, DFS_INFO_101, DFS_INFO_102, NetDfsEnum


NetErrorLogClear

The NetErrorLogClear function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmerrlog.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetErrorLogRead

The NetErrorLogRead function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmerrlog.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetErrorLogWrite

The NetErrorLogWrite function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use event logging.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmerrlog.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetFileClose

The NetFileClose function forces a resource to close. This function can be used when an error prevents closure by any other means. You should use NetFileClose with caution because it does not write data cached on the client system to the file before closing the file.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetFileClose function.

NET_API_STATUS NetFileClose(
  LPWSTR servername,
  DWORD fileid
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
fileid
[in] Specifies the file identifier of the opened resource instance to close.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_FILE_NOT_FOUND | The file was not found.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, NetFile Functions


NetFileClose2

Windows 95/98/Me: The NetFileClose2 function forces a resource to close. This function can be used when an error prevents closure by any other means.

Windows NT/2000 or later: This function is not supported on Windows NT/Windows 2000. Use the NetFileClose function instead.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetFileClose2 function.

extern API_FUNCTION
 NetFileClose2(
  const char FAR * pszServer,
  unsigned long ulFileId
);

Parameters

pszServer
[in] Pointer to an ASCIIZ string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
ulFileId
[in] Specifies the file identifier of the resource instance to close. You can retrieve this value by calling the NetFileEnum function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_NetNotStarted | The workstation driver is not installed.
NERR_ServerNotStarted | The Server service is not started.
NERR_RemoteErr | A remote API error occurred.
NERR_FileIdNotFound | There is not an open file with the specified identification number.

Remarks

The NetFileClose2 function supports file handles that are larger than 64 kilobytes.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h; include Lm.h.
Library: Use Svrapi.lib.

See Also

Network Management Overview, Network Management Functions, NetFile Functions, NetFileEnum


NetFileEnum

The NetFileEnum function returns information about some or all open files on a server, depending on the parameters specified.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetFileEnum function.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetFileEnum(
  LPWSTR servername,
  LPWSTR basepath,
  LPWSTR username,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  PDWORD_PTR resume_handle
);

Windows 95/98/Me: The calling application must use the cbBuffer parameter to specify the size, in bytes, of the information buffer pointed to by the pbBuffer parameter. (The cbBuffer parameter replaces the Windows NT/Windows 2000 prefmaxlen parameter.) Neither a user name parameter nor a resume handle parameter is available on this platform. Therefore, the parameter list is as follows.

extern API_FUNCTION
 NetFileEnum(
  const char FAR * pszServer,
  const char FAR * pszBasePath,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short  cbBuffer,
  unsigned short FAR * pcEntriesRead,
  unsigned short FAR * pcTotalAvail
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
basepath
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying a qualifier for the returned information. If this parameter is NULL, all open resources are enumerated. If this parameter is not NULL, the function enumerates only resources that have basepath as a prefix. (A prefix is the path component up to a backslash.)
username
[in] Pointer to a Unicode string that specifies the name of the user. If this parameter is specified, username serves as a qualifier for the enumeration. The files returned are limited to those that have user names matching the qualifier. If this parameter is NULL, no user-name qualifier is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
2 | Windows NT/2000 or later: Return the file identification number. The bufptr parameter points to an array of FILE_INFO_2 structures.
3 | Windows NT/2000 or later: Return information about the file. The bufptr parameter points to an array of FILE_INFO_3 structures.
50 | Windows 95/98/Me: Return information about the file. The returned buffer contains an array of file_info_50 structures.

bufptr
[out] Pointer to the address of the buffer that receives the information. The format of this data depends on the value of the level parameter.

Windows NT/2000 or later: This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

Windows 95/98/Me: The caller must allocate and deallocate this buffer.

prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a value that receives the total number of entries that could have been enumerated from the current resume position.
resume_handle
[in/out] Pointer to a value that contains a resume handle which is used to continue an existing file search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.

Remarks

You can call the NetFileGetInfo function to retrieve information about a particular opening of a server resource.

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 NetFileEnum. For more information, see IADsResource and IADsFileServiceOperations.

Windows 95/98/Me: See the NetFileEnum Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetFileEnum function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, NetFile Functions, FILE_INFO_2, FILE_INFO_3, file_info_50, NetFileGetInfo


NetFileGetInfo

The NetFileGetInfo function retrieves information about a particular opening of a server resource.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetFileGetInfo function.

NET_API_STATUS NetFileGetInfo(
  LPWSTR servername,
  DWORD fileid,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
fileid
[in] Specifies the file identifier of the open resource for which to return information. The value of this parameter must have been returned in a previous enumeration call. For more information, see the following Remarks section.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
2 | Return the file identification number. The bufptr parameter is a pointer to a FILE_INFO_2 structure.
3 | Return the file identification number and other information about the file. The bufptr parameter is a pointer to a FILE_INFO_3 structure.

bufptr
[out] Pointer to the address of the buffer that receives the information. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_FILE_NOT_FOUND | The file was not found.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.

Remarks

You can call the NetFileEnum function to retrieve information about multiple files open on a server.

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 NetFileGetInfo. For more information, see IADsResource and IADsFileServiceOperations.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, NetFile Functions, FILE_INFO_2, FILE_INFO_3, NetFileEnum


NetGetAnyDCName

The NetGetAnyDCName function returns the name of any domain controller (DC) for a domain that is directly trusted by the specified server.

Windows 2000 or later: Win32-based applications that support DNS-style names should call the DsGetDcName function. DsGetDcName can locate any DC in any domain, whether or not the domain is directly trusted by the specified server.

Security Requirements

No special group membership is required to successfully execute the NetGetAnyDCName function.

NET_API_STATUS NetGetAnyDCName(
  LPCWSTR servername,
  LPCWSTR domainname,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used. For more information, see the following Remarks section.
domainname
[in] Pointer to a constant Unicode string specifying the name of the domain. If this parameter is NULL, the name of the domain controller for the primary domain is used. For more information, see the following Remarks section.
bufptr
[out] Pointer to an allocated buffer that receives a Unicode string specifying the server name of a domain controller for the domain. The server name is prefixed by \\. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_NO_LOGON_SERVERS | No domain controllers could be found.
ERROR_NO_SUCH_DOMAIN | The specified domain is not a trusted domain.
ERROR_NO_TRUST_LSA_SECRET | The client side of the trust relationship is broken.
ERROR_NO_TRUST_SAM_ACCOUNT | The server side of the trust relationship is broken or the password is broken.
ERROR_DOMAIN_TRUST_INCONSISTENT | The server that responded is not a proper domain controller of the specified domain.

Remarks

If servername specifies a stand-alone Windows NT/Windows 2000 workstation or a stand-alone server, no domainname is valid.

If servername specifies a Windows NT/Windows 2000 workstation that is a member of a domain, or a Windows NT/Windows 2000 server that is a member of a domain, the domainname must be in the same domain as servername.

If servername specifies a domain controller, the domainname must be one of the domains trusted by the domain for which the server is a controller. The domain controller that this call finds has been operational at least once during this call.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Get Functions, DsGetDcName, NetGetDCName


NetGetDCName

The NetGetDCName function returns the name of the primary domain controller (PDC). It does not return the name of the backup domain controller (BDC) for the specified domain. Also, you cannot remote this function to a non-PDC server.

Windows 2000 or later: Win32-based applications that support DNS-style names should call the DsGetDcName function. Domain controllers in a Windows 2000 environment have a multi-master directory replication relationship. Therefore, it may be advantageous for your application to use a DC that is not the PDC. You can call the DsGetDcName function to locate any DC in the domain; NetGetDCName returns only the name of the PDC.

Security Requirements

No special group membership is required to successfully execute the NetGetDCName function.

NET_API_STATUS NetGetDCName(
  LPCWSTR servername,
  LPCWSTR domainname,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
domainname
[in] Pointer to a constant Unicode string specifying the name of the domain. The domain name must be a NetBIOS domain name (for example, microsoft). NetGetDCName does not support DNS-style names (for example, microsoft.com). If this parameter is NULL, the function returns the name of the domain controller for the primary domain.
bufptr
[out] Pointer to an allocated buffer that receives a Unicode string which specifies the server name of the PDC of the domain. The server name is prefixed by \\. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
NERR_DCNotFound | Could not find the domain controller for the domain.
ERROR_INVALID_NAME | The name could not be found.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Get Functions, DsGetDcName, NetGetAnyDCName


NetGetDisplayInformationIndex

The NetGetDisplayInformationIndex function returns the index of the first display information entry whose name begins with a specified string or whose name alphabetically follows the string. You can use this function to determine a starting index for subsequent calls to the NetQueryDisplayInformation function.

Security Requirements

No special group membership is required to successfully execute the NetGetDisplayInformationIndex function.

NET_API_STATUS NetGetDisplayInformationIndex(
  LPCWSTR ServerName,
  DWORD Level,
  LPCWSTR Prefix,
  LPDWORD Index
);

Parameters

ServerName
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
Level
[in] Specifies the level of accounts to query. This parameter can be one of the following values.
Value | Meaning
1 | Query all local and global (normal) user accounts.
2 | Query all workstation and server user accounts.
3 | Query all global groups.

Prefix
[in] Pointer to a constant null-terminated Unicode string specifying the prefix for which to search.
Index
[out] Pointer to a DWORD value that receives the index of the requested entry.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the Level parameter is invalid.
ERROR_NO_MORE_ITEMS | There were no more items on which to operate.
NERR_InvalidComputer | The computer name is invalid.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Get Functions, NetQueryDisplayInformation


NetGetJoinableOUs

The NetGetJoinableOUs function retrieves a list of organizational units (OUs) in which a computer account can be created.

Security Requirements

No special group membership is required to successfully execute the NetGetJoinableOUs function.

NET_API_STATUS NetGetJoinableOUs(
  LPCWSTR lpServer,
  LPCWSTR lpDomain,
  LPCWSTR lpAccount,
  LPCWSTR lpPassword,
  DWORD *OUCount,
  LPWSTR **OUs
);

Parameters

lpServer
[in] Pointer to a constant null-terminated Unicode character string that specifies the name of the computer on which to call the function. If this parameter is NULL, the local computer is used.
lpDomain
[in] Pointer to a constant null-terminated Unicode character string that specifies the name of the domain for which to retrieve the list of OUs that can be joined.
lpAccount
[in] Pointer to a constant null-terminated Unicode character string that specifies the account name to use when connecting to the domain controller. The string must specify either a domain NetBIOS name and user account (for example, "REDMOND\user") or the user principal name (UPN) of the user in the form of an Internet-style login name (for example, "someone@microsoft.com"). If this parameter is NULL, the caller's context is used.
lpPassword
[in] If the lpAccount parameter specifies an account name, this parameter must point to the password to use when connecting to the domain controller. Otherwise, this parameter must be NULL.
OUCount
[out] Receives the count of OUs returned in the list of joinable OUs.
OUs
[out] Pointer to an array that receives the list of joinable OUs. This array is allocated by the system and must be freed using a single call to the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes or one of the Win32 error codes.

Value | Meaning
ERROR_NOT_ENOUGH_MEMORY | Not enough storage is available to process this command.
NERR_DefaultJoinRequired | The destination domain controller does not support creating computer accounts in OUs.

Remarks

For more information about organizational units, see Managing Users in the Active Directory documentation.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmjoin.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, NetGetJoinInformation


NetGetJoinInformation

The NetGetJoinInformation function retrieves join status information for the specified computer.

Security Requirements

No special group membership is required to successfully execute the NetGetJoinInformation function.

NET_API_STATUS NetGetJoinInformation(
  LPCWSTR lpServer,
  LPWSTR *lpNameBuffer,
  PNETSETUP_JOIN_STATUS BufferType
);

Parameters

lpServer
[in] Pointer to a constant null-terminated Unicode character string that specifies the name of the computer on which to call the function. If this parameter is NULL, the local computer is used.
lpNameBuffer
[out] Pointer to the buffer that receives the name of the domain or workgroup to which the computer is joined. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.
BufferType
[out] Receives the join status of the specified computer. This parameter can have one of the following values.
typedef enum _NETSETUP_JOIN_STATUS {

    NetSetupUnknownStatus = 0,
    NetSetupUnjoined,
    NetSetupWorkgroupName,
    NetSetupDomainName

} NETSETUP_JOIN_STATUS, *PNETSETUP_JOIN_STATUS;

These values have the following meanings.
Value | Meaning
NetSetupUnknownStatus | The status is unknown.
NetSetupUnjoined | The computer is not joined.
NetSetupWorkgroupName | The computer is joined to a workgroup.
NetSetupDomainName | The computer is joined to a domain.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be the following error code or one of the Win32 error codes.

Value | Meaning
ERROR_NOT_ENOUGH_MEMORY | Not enough storage is available to process this command.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmjoin.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, NetGetJoinableOUs


NetGroupAdd

The NetGroupAdd function creates a global group in the security database.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetGroupAdd function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupAdd(
  LPCWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies a global group name. The buf parameter contains a pointer to a GROUP_INFO_0 structure.
1 | Specifies a global group name and a comment. The buf parameter contains a pointer to a GROUP_INFO_1 structure.
2 | Specifies detailed information about the global group. The buf parameter contains a pointer to a GROUP_INFO_2 structure. Note that on Whistler and later, it is recommended that you use GROUP_INFO_3 instead.
3 | Whistler: Specifies detailed information about the global group. The buf parameter contains a pointer to a GROUP_INFO_3 structure.

buf
[in] Pointer to a buffer that contains the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the global group information structure in error when ERROR_INVALID_PARAMETER is returned. If this parameter is NULL, the index is not returned on error. For more information, see the NetGroupSetInfo function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_GroupExists | The global group already exists.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
NERR_SpeGroupOp | The operation is not allowed on certain special groups. These groups include user groups, admin groups, local groups, and guest groups.

Remarks

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, GROUP_INFO_0, GROUP_INFO_1, GROUP_INFO_3, NetGroupAddUser, NetGroupDel, NetGroupSetInfo, NetGroupDelUser


NetGroupAddUser

The NetGroupAddUser function gives an existing user account membership in an existing global group in the security database.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetGroupAddUser function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstaion only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupAddUser(
  LPCWSTR servername,
  LPCWSTR GroupName,
  LPCWSTR username
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
GroupName
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the global group in which the user is to be given membership.
username
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the user to be given membership in the global group.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_SpeGroupOp | The operation is not allowed on certain special groups. These groups include user groups, admin groups, local groups, and guest groups.
NERR_UserNotFound | The user name could not be found.
NERR_GroupNotFound | The global group name could not be found.

Remarks

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, NetGroupAdd, NetGroupDel, NetGroupDelUser


NetGroupDel

The NetGroupDel function deletes a global group from the security database.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetGroupDel function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupDel(
  LPCWSTR servername,
  LPCWSTR groupname
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the global group account to delete.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_SpeGroupOp | The operation is not allowed on certain special groups. These groups include user groups, admin groups, local groups, and guest groups.
NERR_GroupNotFound | The global group name could not be found.

Remarks

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, NetGroupAdd, NetGroupDelUser, NetGroupAddUser


NetGroupDelUser

The NetGroupDelUser function removes a user from a particular global group in the security database.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetGroupDelUser function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupDelUser(
  LPCWSTR servername,
  LPCWSTR GroupName,
  LPCWSTR Username
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
GroupName
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the global group from which the user's membership should be removed.
Username
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the user to remove from the global group.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_SpeGroupOp | The operation is not allowed on certain special groups. These groups include user groups, admin groups, local groups, and guest groups.
NERR_UserNotFound | The user name could not be found.
NERR_GroupNotFound | The global group name could not be found.
NERR_UserNotInGroup | The user does not belong to this global group.

Remarks

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, NetGroupAddUser, NetGroupDel, NetGroupAdd


NetGroupEnum

The NetGroupEnum function retrieves information about each global group in the security database.

The NetQueryDisplayInformation function provides an efficient mechanism for enumerating global groups. When possible, it is recommended that you use NetQueryDisplayInformation instead of the NetGroupEnum function.

Security Requirements

Windows NT: No special group membership is required to successfully execute the NetGroupEnum function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupEnum(
  LPCWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  PDWORD_PTR resume_handle
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the global group name. The bufptr parameter points to an array of GROUP_INFO_0 structures.
1 | Return the global group name and a comment. The bufptr parameter points to an array of GROUP_INFO_1 structures.
2 | Return detailed information about the global group. The bufptr parameter points to an array of GROUP_INFO_2 structures. Note that on Whistler and later, it is recommended that you use GROUP_INFO_3 instead.
3 | Whistler: Return detailed information about the global group. The bufptr parameter points to an array of GROUP_INFO_3 structures.

bufptr
[out] Pointer to the buffer to receive the global group information structure. The format of this data depends on the value of the level parameter.

The system allocates the memory for this buffer. You must call the NetApiBufferFree function to deallocate the memory. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

prefmaxlen
[in] Specifies the preferred maximum length of the returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required to hold the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resume_handle
[in/out] Pointer to a variable that contains a resume handle that is used to continue the global group enumeration. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.

Remarks

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, GROUP_INFO_0, GROUP_INFO_1, GROUP_INFO_3, NetQueryDisplayInformation, NetGroupGetInfo, NetGroupGetUsers, NetApiBufferFree


NetGroupGetInfo

The NetGroupGetInfo function retrieves information about a particular global group in the security database.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetGroupGetInfo function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupGetInfo(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the global group for which to retrieve information.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the global group name. The bufptr parameter points to a GROUP_INFO_0 structure.
1 | Return the global group name and a comment. The bufptr parameter points to a GROUP_INFO_1 structure.
2 | Return detailed information about the global group. The bufptr parameter points to a GROUP_INFO_2 structure. Note that on Whistler and later, it is recommended that you use GROUP_INFO_3 instead.
3 | Whistler: Return detailed information about the global group. The bufptr parameter points to a GROUP_INFO_3 structure.

bufptr
[out] Pointer to the address of the buffer that receives the global group information structure. The format of this data depends on the value of the level parameter. The system allocates the memory for this buffer. You must call the NetApiBufferFree function to deallocate the memory.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_GroupNotFound | The global group name could not be found.

Remarks

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, GROUP_INFO_0, GROUP_INFO_1, GROUP_INFO_3, NetGroupSetInfo, NetApiBufferFree


NetGroupGetUsers

The NetGroupGetUsers function retrieves a list of the members in a particular global group in the security database.

Security Requirements

Windows NT: No special group membership is required to successfully execute the NetGroupGetUsers function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupGetUsers(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  PDWORD_PTR ResumeHandle
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the global group whose members are to be listed.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Return the global group's member names. The bufptr parameter points to an array of GROUP_USERS_INFO_0 structures.

bufptr
[out] Pointer to the address of the buffer that receives the information structure. The system allocates the memory for this buffer. You must call the NetApiBufferFree function to deallocate the memory. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of the returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required to hold the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
ResumeHandle
[in/out] Pointer to a variable that contains a resume handle that is used to continue an existing user enumeration. The handle should be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_GroupNotFound | The global group name could not be found.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.

Remarks

To grant one user membership in an existing global group, you can call the NetGroupAddUser function. To remove a user from a global group, call the NetGroupDelUser function. For information about replacing the membership of a global group, see NetGroupSetUsers.

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, GROUP_USERS_INFO_0, NetGroupSetUsers, NetApiBufferFree, NetUserGetGroups, NetGroupAddUser, NetGroupDelUser, NetQueryDisplayInformation


NetGroupSetInfo

The NetGroupSetInfo function sets the parameters of a global group in the security database.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetGroupSetInfo function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupSetInfo(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the global group for which to set information.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies a global group name. The buf parameter points to a GROUP_INFO_0 structure.
1 | Specifies a global group name and a comment. The buf parameter points to a GROUP_INFO_1 structure.
2 | Specifies detailed information about the global group. The buf parameter points to a GROUP_INFO_2 structure. Note that on Whistler and later, it is recommended that you use GROUP_INFO_3 instead.
3 | Whistler: Specifies detailed information about the global group. The buf parameter points to a GROUP_INFO_3 structure.
1002 | Specifies a comment only about the global group. The buf parameter points to a GROUP_INFO_1002 structure.
1005 | Specifies global group attributes. The buf parameter points to a GROUP_INFO_1005 structure.

For more information, see the following Remarks section.

buf
[in] Pointer to a buffer that contains the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the group information structure in error following an ERROR_INVALID_PARAMETER error code. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid. For more information, see the following Remarks section.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupNotFound | The global group name could not be found.
NERR_SpeGroupOp | The operation is not allowed on certain special groups. These groups include user groups, admin groups, local groups, and guest groups.

Remarks

The correct way to set the new name of a global group is to call the NetGroupSetInfo function, using a GROUP_INFO_0 structure. Specify the new value in the grpi0_name member. If you use a GROUP_INFO_1 structure and specify the value in the grpi1_name member, the new name value is ignored.

If the NetGroupSetInfo function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the group information structure that is invalid. (A group information structure begins with GROUP_INFO_ and its format is specified by the level parameter.) The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error. (The prefix grpi*_ indicates that the member can begin with multiple prefixes, for example, grpi1_ or grpi2_.)

Value | Member
GROUP_NAME_PARMNUM | grpi*_name
GROUP_COMMENT_PARMNUM | grpi*_comment
GROUP_ATTRIBUTES_PARMNUM | grpi*_attributes

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, GROUP_INFO_0, GROUP_INFO_1, GROUP_INFO_3, GROUP_INFO_1002, GROUP_INFO_1005, NetGroupGetInfo


NetGroupSetUsers

The NetGroupSetUsers function sets the membership for the specified global group. Each user you specify is enrolled as a member of the global group. Users you do not specify, but who are currently members of the global group, will have their membership revoked.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetGroupSetUsers function on a remote server.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetGroupSetUsers(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE buf,
  DWORD totalentries
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant null-terminated Unicode character string specifying the name of the global group of interest.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | The buf parameter points to an array of GROUP_USERS_INFO_0 structures that specify user names.

buf
[in] Pointer to the buffer that contains the data.
totalentries
[in] Specifies the number of entries in the buffer pointed to by the buf parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupNotFound | The global group name could not be found.
NERR_UserNotFound | The user name could not be found.
NERR_SpeGroupOp | The operation is not allowed on certain special groups. These groups include user groups, admin groups, local groups, and guest groups.

Remarks

You can replace the global group membership with an entirely new list of members by calling the NetGroupSetUsers function. The typical sequence of steps to perform this follows.

To replace the global group membership

  1. Call the NetGroupGetUsers function to retrieve the current membership list.
  2. Modify the returned membership list to reflect the new membership.
  3. Call the NetGroupSetUsers function to replace the old membership list with the new membership list.

To grant one user membership in an existing global group, you can call the NetGroupAddUser function. To remove a user from a global group, call the NetGroupDelUser function.

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 group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Group Functions, NetGroupGetUsers, NetUserGetGroups, NetUserSetGroups, NetGroupAddUser, NetGroupDelUser, GROUP_USERS_INFO_0


NetJoinDomain

The NetJoinDomain function joins a computer to a workgroup or domain.

Security Requirements

Joining (and unjoining) a computer to a domain or workgroup can be performed only by a member of the Administrators local group on the target computer. Note that the domain administrator can set additional requirements for joining the domain using delegation and assignment of privileges.

If you call the NetJoinDomain function remotely, you must supply credentials because you cannot delegate credentials under these circumstances.

NET_API_STATUS NetJoinDomain(
  LPCWSTR lpServer,
  LPCWSTR lpDomain,
  LPCWSTR lpAccountOU,
  LPCWSTR lpAccount,
  LPCWSTR lpPassword,
  DWORD fJoinOptions
);

Parameters

lpServer
[in] Pointer to a constant null-terminated character string that specifies the name of the computer on which to call the function. If this parameter is NULL, the local computer is used.
lpDomain
[in] Pointer to a constant null-terminated character string that specifies the name of the domain or workgroup to join.

Optionally, you can specify the preferred domain controller to perform the join operation. In this instance, the string must be of the form DomainName\MachineName, where DomainName is the name of the domain to join, and MachineName is the name of the domain controller to perform the join.

lpAccountOU
[in] Optionally specifies the pointer to a constant null-terminated character string that contains the RFC 1779 format name of the organizational unit (OU) for the computer account. If you specify this parameter, the string must contain a full path, for example, OU=testOU,DC=domain,DC=Domain,DC=com. Otherwise, this parameter must be NULL.
lpAccount
[in] Pointer to a constant null-terminated character string that specifies the account name to use when connecting to the domain controller. The string must specify either a domain NetBIOS name and user account (for example, "REDMOND\user") or the user principal name (UPN) of the user in the form of an Internet-style login name (for example, "someone@microsoft.com"). If this parameter is NULL, the caller's context is used.
lpPassword
[in] If the lpAccount parameter specifies an account name, this parameter must point to the password to use when connecting to the domain controller. Otherwise, this parameter must be NULL.

You can specify a local machine account password rather than a user password for unsecured joins. For more information, see the description of the NETSETUP_MACHINE_PWD_PASSED flag described in the fJoinOptions parameter.

fJoinOptions
[in] Specifies a DWORD value that contains a set of bit flags defining the join options. This parameter can be one or more of the following values.
Value | Meaning
NETSETUP_JOIN_DOMAIN | Joins the computer to a domain. If this value is not specified, joins the computer to a workgroup.
NETSETUP_ACCT_CREATE | Creates the account on the domain.
NETSETUP_WIN9X_UPGRADE | The join operation is occurring as part of an upgrade of Windows 95/98 to Windows NT/Windows 2000.
NETSETUP_DOMAIN_JOIN_IF_JOINED | Allows a join to a new domain even if the computer is already joined to a domain.
NETSETUP_JOIN_UNSECURE | Performs an unsecured join.
NETSETUP_MACHINE_PWD_PASSED Whistler: Indicates that the lpPassword parameter specifies a local machine account password rather than a user password. This flag is valid only for unsecured joins, which you must indicate by also setting the NETSETUP_JOIN_UNSECURE flag.

If you set this flag, then after the join operation succeeds, the machine password will be set to the value of lpPassword, if that value is a valid machine password.

NETSETUP_DEFER_SPN_SET | Whistler: Indicates that the service principal name (SPN) and the DnsHostName properties on the computer object should not be updated at this time. (Typically, these properties are updated during the join operation.) Instead, these properties should be updated during a subsequent call to the NetRenameMachineInDomain function. (These properties are always updated during the rename operation.) For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes or one of the Win32 error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter is incorrect.
ERROR_NO_SUCH_DOMAIN | The specified domain did not exist.
NERR_SetupAlreadyJoined | The computer is already joined to a domain.
NERR_InvalidWorkgroupName | The specified workgroup name is not valid.

Remarks

Different processes, or different threads of the same process, should not call the NetJoinDomain function at the same time. This situation can leave the computer in an inconsistent state.

If you encounter a problem during a join operation, you should not delete a computer account and immediately follow the deletion with another join attempt. This can lead to replication-related problems that are difficult to investigate. When you delete a computer account, wait until the change has replicated to all domain controllers before attempting another join operation.

Whistler: When a call to the NetJoinDomain function precedes a call to the NetRenameMachineInDomain function, you should defer the update of the SPN and DnsHostName properties on the computer object until the rename operation. This is because the join operation can fail in certain situations. An example of such a situation is when the SPN that is derived from the current computer name is not valid in the new domain that the computer is joining, but the SPN derived from the new name that the computer will have after the rename operation is valid in the new domain. In this situation, the call to NetJoinDomain fails unless you defer the update of the two properties until the rename operation by specifying the NETSETUP_DEFER_SPN_SET flag in the fJoinOptions parameter when you call NetJoinDomain.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmjoin.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, NetUnjoinDomain, NetRenameMachineInDomain


NetLocalGroupAdd

The NetLocalGroupAdd function creates a local group in the security database.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupAdd function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupAdd(
  LPCWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant Unicode character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies a local group name. The buf parameter points to a LOCALGROUP_INFO_0 structure.
1 | Specifies a local group name and a comment to associate with the group. The buf parameter points to a LOCALGROUP_INFO_1 structure.

buf
[in] Pointer to a buffer containing the local group information structure. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the local group information structure to cause the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error. For more information, see the Remarks section in the NetLocalGroupSetInfo topic.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupExists | The local group already exists.
ERROR_ALIAS_EXISTS | The local group already exists.

Remarks

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, LOCALGROUP_INFO_0, LOCALGROUP_INFO_1, NetLocalGroupDel, NetLocalGroupSetInfo, NetLocalGroupAddMembers


NetLocalGroupAddMember

The NetLocalGroupAddMember function is obsolete. Win32-based applications should use the NetLocalGroupAddMembers function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions


NetLocalGroupAddMembers

The NetLocalGroupAddMembers function adds membership of one or more existing user accounts or global group accounts to an existing local group. The function does not change the membership status of users or global groups that are currently members of the local group.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupAddMembers function on a remote server.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupAddMembers(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE buf,
  DWORD totalentries
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant null-terminated Unicode string specifying the name of the local group to which the specified users or global groups will be added.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies the security identifier (SID) of the new local group member. The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.
3 | Specifies the domain and name of the new local group member. The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures.

buf
[in] Pointer to a buffer containing the data for the new local group members. The format of this data depends on the value of the level parameter.
totalentries
[in] Specifies the number of entries in the buffer pointed to by the buf parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
NERR_GroupNotFound | The local group specified by the groupname parameter does not exist.
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_NO_SUCH_MEMBER | One or more of the members specified do not exist. Therefore, no new members were added.
ERROR_MEMBER_IN_ALIAS | One or more of the members specified were already members of the local group. No new members were added.
ERROR_INVALID_MEMBER | One or more of the members cannot be added because their account type is invalid. No new members were added.

Remarks

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_3, NetLocalGroupDelMembers, NetLocalGroupGetMembers, NetLocalGroupAdd, NetLocalGroupDel


NetLocalGroupDel

The NetLocalGroupDel function deletes a local group account and all its members from the security database.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupDel function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupDel(
  LPCWSTR servername,
  LPCWSTR groupname
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant Unicode string specifying the name of the local group account to delete.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupNotFound | The local group specified by the groupname parameter does not exist.
ERROR_NO_SUCH_ALIAS | The specified local group does not exist.

Remarks

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, NetLocalGroupAdd, NetLocalGroupDelMembers


NetLocalGroupDelMember

The NetLocalGroupDelMember function is obsolete. Win32-based applications should use the NetLocalGroupDelMembers function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions


NetLocalGroupDelMembers

The NetLocalGroupDelMembers function removes one or more members from an existing local group. Local group members can be users or global groups.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupDelMembers function on a remote server.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupDelMembers(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE buf,
  DWORD totalentries
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant null-terminated Unicode string specifying the name of the local group from which the specified users or global groups will be removed.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies the security identifier (SID) of a local group member to remove. The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.
3 | Specifies the domain and name of a local group member to remove. The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures.

buf
[in] Pointer to a buffer specifying the members to be removed. The format of this data depends on the value of the level parameter.
totalentries
[in] Specifies the number of entries in the array pointed to by the buf parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_GroupNotFound | The local group specified by the groupname parameter does not exist.
ERROR_NO_SUCH_MEMBER | One or more of the specified members do not exist. No members were deleted.
ERROR_MEMBER_NOT_IN_ALIAS | One or more of the members specified were not members of the local group. No members were deleted.

Remarks

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_3, NetLocalGroupAddMembers, NetLocalGroupDel, NetLocalGroupGetMembers


NetLocalGroupEnum

The NetLocalGroupEnum function returns information about each local group account on the specified server.

Security Requirements

Windows NT: No special group membership is required to successfully execute the NetLocalGroupEnum function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupEnum(
  LPCWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  PDWORD_PTR resumehandle
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return local group names. The bufptr parameter points to an array of LOCALGROUP_INFO_0 structures.
1 | Return local group names and the comment associated with each group. The bufptr parameter points to an array of LOCALGROUP_INFO_1 structures.

bufptr
[out] Pointer to the address of the buffer that receives the information structure. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the approximate total number of entries that could have been enumerated from the current resume position. For more information, see the following Remarks section.
resumehandle
[in/out] Pointer to a value that contains a resume handle that is used to continue an existing local group search. The handle should be zero on the first call and left unchanged for subsequent calls. If this parameter is NULL, then no resume handle is stored. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
NERR_InvalidComputer | The computer name is invalid.
NERR_BufTooSmall | The return buffer is too small.

Remarks

To determine the exact total number of local groups, you must enumerate the entire tree, which can be a costly operation. To enumerate the entire tree, use the resumehandle parameter to continue the enumeration for consecutive calls, and use the entriesread parameter to accumulate the total number of local groups.

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, LOCALGROUP_INFO_0, LOCALGROUP_INFO_1, NetQueryDisplayInformation, NetLocalGroupGetInfo, NetLocalGroupGetMembers


NetLocalGroupGetInfo

The NetLocalGroupGetInfo function retrieves information about a particular local group account on a server.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupGetInfo function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupGetInfo(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant Unicode string containing the name of the local group account for which the information will be retrieved.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
1 | Return the comment associated with the local group. The bufptr parameter points to a LOCALGROUP_INFO_1 structure.

bufptr
[out] Pointer to the address of the buffer that receives the return information structure. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_NO_SUCH_ALIAS | The specified local group does not exist.

Remarks

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, LOCALGROUP_INFO_1, NetQueryDisplayInformation, NetLocalGroupEnum, NetLocalGroupGetMembers, NetLocalGroupSetInfo


NetLocalGroupGetMembers

The NetLocalGroupGetMembers function retrieves a list of the members of a particular local group in the security database. Local group members can be users or global groups.

Security Requirements

Windows NT: No special group membership is required to successfully execute the NetLocalGroupGetMembers function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupGetMembers(
  LPCWSTR servername,
  LPCWSTR localgroupname,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  PDWORD_PTR resumehandle
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
localgroupname
[in] Pointer to a constant Unicode string specifying the name of the local group whose members are to be listed.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the security identifier (SID) associated with the local group member. The bufptr parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.
1 | Return the SID and account information associated with the local group member. The bufptr parameter points to an array of LOCALGROUP_MEMBERS_INFO_1 structures.
2 | Return the SID, account information, and the domain name associated with the local group member. The bufptr parameter points to an array of LOCALGROUP_MEMBERS_INFO_2 structures.
3 | Return the account and domain names of the local group member. The bufptr parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures.

bufptr
[out] Pointer to the address that receives the return information structure. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resumehandle
[in/out] Pointer to a value that contains a resume handle which is used to continue an existing group member search. The handle should be zero on the first call and left unchanged for subsequent calls. If this parameter is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_NO_SUCH_ALIAS | The specified local group does not exist.

Remarks

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_1, LOCALGROUP_MEMBERS_INFO_2, LOCALGROUP_MEMBERS_INFO_3, NetLocalGroupSetMembers, NetLocalGroupGetInfo, NetLocalGroupEnum


NetLocalGroupSetInfo

The NetLocalGroupSetInfo function changes the name of an existing local group. The function also associates a comment with a local group.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupSetInfo function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupSetInfo(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant Unicode string containing the name of the local group account to modify.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies the local group name. The buf parameter points to a LOCALGROUP_INFO_0 structure. Use this level to change the name of an existing local group.
1 | Specifies the local group name and a comment to associate with the group. The buf parameter points to a LOCALGROUP_INFO_1 structure.
1002 | Specifies a comment to associate with the local group. The buf parameter points to a LOCALGROUP_INFO_1002 structure.

buf
[in] Pointer to a buffer containing the local group information. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the local group information structure that caused the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid. For more information, see the following Remarks section.
ERROR_NO_SUCH_ALIAS | The specified local group does not exist.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_InvalidComputer | The computer name is invalid.

Remarks

To specify the new name of an existing local group, call NetLocalGroupSetInfo with LOCALGROUP_INFO_0 and specify a value using the lgrpi0_name member. If you call the NetLocalGroupSetInfo function with LOCALGROUP_INFO_1 and specify a new value using the lgrpi1_name member, that value will be ignored.

If the NetLocalGroupSetInfo function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the local group information structure that is invalid. (A local group information structure begins with LOCALGROUP_INFO_ and its format is specified by the level parameter.) The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error. (The prefix lgrpi*_ indicates that the member can begin with multiple prefixes, for example, lgrpi0_ or lgrpi1_.)

Value | Member
LOCALGROUP_NAME_PARMNUM | lgrpi*_name
LOCALGROUP_COMMENT_PARMNUM | lgrpi*_comment

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, LOCALGROUP_INFO_0, LOCALGROUP_INFO_1, LOCALGROUP_INFO_1002, NetLocalGroupGetInfo


NetLocalGroupSetMembers

The NetLocalGroupSetMembers function sets the membership for the specified local group. Each user or global group specified is made a member of the local group. Users or global groups that are not specified but who are currently members of the local group will have their membership revoked.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetLocalGroupSetMembers function on a remote server.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetLocalGroupSetMembers(
  LPCWSTR servername,
  LPCWSTR groupname,
  DWORD level,
  LPBYTE buf,
  DWORD totalentries
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
groupname
[in] Pointer to a constant Unicode string specifying the name of the local group in which the specified users or global groups should be granted membership.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies the security identifier (SID) associated with a local group member. The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_0 structures.
3 | Specifies the account and domain names of the local group member. The buf parameter points to an array of LOCALGROUP_MEMBERS_INFO_3 structures.

buf
[in] Pointer to the buffer containing the member information. The format of this data depends on the value of the level parameter.
totalentries
[in] Specifies a DWORD value that contains the total number of entries in the buffer pointed to by the buf parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
NERR_GroupNotFound | The group specified by the groupname parameter does not exist.
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_NO_SUCH_MEMBER | One or more of the members doesn't exist. The local group membership was not changed.
ERROR_INVALID_MEMBER | One or more of the members cannot be added because it has an invalid account type. The local group membership was not changed.

Remarks

You can replace the local group membership with an entirely new list of members by calling the NetLocalGroupSetMembers function. The typical sequence of steps to perform this follows.

To replace the local group membership

  1. Call the NetLocalGroupGetMembers function to retrieve the current membership list.
  2. Modify the returned membership list to reflect the new membership.
  3. Call the NetLocalGroupSetMembers function to replace the old membership list with the new membership list.

To add one or more existing user accounts or global group accounts to an existing local group, you can call the NetLocalGroupAddMembers function. To remove one or more members from an existing local group, call the NetLocalGroupDelMembers function.

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 local group functions. For more information, see IADsGroup.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Local Group Functions, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_3, NetLocalGroupGetMembers, NetLocalGroupAddMembers, NetLocalGroupDelMembers


NetMessageBufferSend

The NetMessageBufferSend function sends a buffer of information to a registered message alias.

Security Requirements

Windows NT: No special group membership is required to execute the NetMessageBufferSend function on a LAN Manager or a Windows NT system. Admin, Accounts, Print, or Server operator group membership is required to successfully execute NetMessageBufferSend on a remote server.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetMessageBufferSend(
  LPCWSTR servername,
  LPCWSTR msgname,
  LPCWSTR fromname,
  LPBYTE buf,
  DWORD buflen
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
msgname
[in] Pointer to a constant Unicode string specifying the message alias to which the message buffer should be sent.
fromname
[in] Pointer to a constant Unicode string specifying who the message is from. If this parameter is NULL, the message is sent from the local computer name.
buf
[in] Pointer to a buffer that contains the message text.
buflen
[in] Specifies a DWORD value that contains the length, in bytes, of the message text pointed to by the buf parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_SUPPORTED | This network request is not supported.
NERR_NameNotFound | The user name could not be found.
NERR_NetworkError | A general failure occurred in the network hardware.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmmsg.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Message Functions, NetMessageNameAdd, NetMessageNameDel, NetMessageNameEnum, NetMessageNameGetInfo


NetMessageNameAdd

The NetMessageNameAdd function registers a message alias in the message name table. The function requires that the messenger service be started.

Security Requirements

Only members of the Administrators local group can successfully execute the NetMessageNameAdd function on a remote server.

NET_API_STATUS NetMessageNameAdd(
  LPCWSTR servername,
  LPCWSTR msgname
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
msgname
[in] Pointer to a constant Unicode string specifying the message alias to add. The string cannot be more than 15 characters long.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
NERR_AlreadyExists | The message alias already exists on this computer. For more information, see the following Remarks section.
NERR_DuplicateName | The name specified is already in use as a message alias on the network.
NERR_NetworkError | A general failure occurred in the network hardware.
NERR_TooManyNames | The maximum number of message aliases has been exceeded.

Remarks

The forward action flag is no longer a parameter to the LAN Manager 2.x NetMessageNameAdd function because message forwarding is no longer supported. If the NetMessageNameAdd function detects that a forwarded version of msgname exists on the network, the function will fail with error NERR_Already_Exists.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmmsg.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Message Functions, NetMessageNameDel


NetMessageNameDel

The NetMessageNameDel function deletes a message alias in the message name table. The function requires that the messenger service be started.

Security Requirements

Only members of the Administrators local group can successfully execute the NetMessageNameDel function on a remote server.

NET_API_STATUS NetMessageNameDel(
  LPCWSTR servername,
  LPCWSTR msgname
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
msgname
[in] Pointer to a constant Unicode string specifying the message alias to delete. The string cannot be more than 15 characters long.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_DelComputerName | A message alias that is also a computer name cannot be deleted.
NERR_IncompleteDel | The message alias was not successfully deleted from all networks.
NERR_NameInUse | The message alias is currently in use. Try again later.
NERR_NotLocalName | The message alias is not on the local computer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmmsg.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Message Functions, NetMessageNameAdd


NetMessageNameEnum

The NetMessageNameEnum function lists the message aliases that receive messages on a specified computer. The function requires that the messenger service be started.

Security Requirements

Only members of the Administrators local group can successfully execute the NetMessageNameEnum function on a remote server.

NET_API_STATUS NetMessageNameEnum(
  LPCWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return message aliases. The bufptr parameter points to an array of MSG_INFO_0 structures.
1 | Return message aliases. The bufptr parameter points to an array of MSG_INFO_1 structures. This level exists only for compatibility. Message forwarding is not supported.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of the returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resume_handle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing message alias search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.

Remarks

To retrieve information about a particular message alias in the message name table, you can call the NetMessageNameGetInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmmsg.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Message Functions, MSG_INFO_0, MSG_INFO_1, NetMessageNameGetInfo


NetMessageNameGetInfo

The NetMessageNameGetInfo function retrieves information about a particular message alias in the message name table. The function requires that the messenger service be started.

Security Requirements

Only members of the Administrators local group can successfully execute the NetMessageNameGetInfo function on a remote server.

NET_API_STATUS NetMessageNameGetInfo(
  LPCWSTR servername,
  LPCWSTR msgname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
msgname
[in] Pointer to a constant Unicode string specifying the message alias for which to return information.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the message alias. The bufptr parameter points to a MSG_INFO_0 structure.
1 | Return the message alias. The bufptr parameter points to a MSG_INFO_1 structure. This level exists only for compatibility. Message forwarding is not supported.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_NotLocalName | The message alias is not on the local computer.

Remarks

To list all the message aliases in a message name table, you can call the NetMessageNameEnum function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmmsg.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Message Functions, MSG_INFO_0, MSG_INFO_1, NetMessageNameEnum


NetQueryDisplayInformation

The NetQueryDisplayInformation function returns user account, computer, or group account information. Call this function to quickly enumerate account information for display in user interfaces.

Security Requirements

Windows NT: No special group membership is required to successfully execute the NetQueryDisplayInformation function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetQueryDisplayInformation(
  LPCWSTR ServerName,
  DWORD Level,
  DWORD Index,
  DWORD EntriesRequested,
  DWORD PreferredMaximumLength,
  LPDWORD ReturnedEntryCount,
  PVOID *SortedBuffer
);

Parameters

ServerName
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
Level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
1 | Return user account information. The SortedBuffer parameter points to an array of NET_DISPLAY_USER structures.
2 | Return individual computer information. The SortedBuffer parameter points to an array of NET_DISPLAY_MACHINE structures.
3 | Return group account information. The SortedBuffer parameter points to an array of NET_DISPLAY_GROUP structures.

Index
[in] Specifies the index of the first entry for which to retrieve information. Specify zero to retrieve account information beginning with the first display information entry. For more information, see the following Remarks section.
EntriesRequested
[in] Specifies the maximum number of entries for which to retrieve information. On Windows 2000, each call to NetQueryDisplayInformation returns a maximum of 100 objects.
PreferredMaximumLength
[in] Specifies the preferred maximum size, in bytes, of the system-allocated buffer returned in the SortedBuffer parameter. It is recommended that you set this parameter to 0xFFFFFFFF.
ReturnedEntryCount
[out] Pointer to a DWORD value that receives the number of entries in the buffer returned in the SortedBuffer parameter. If this parameter is zero, there are no entries with an index as large as that specified. Entries may be returned when the function's return value is either NERR_Success or ERROR_MORE_DATA.
SortedBuffer
[out] Pointer to a buffer that receives a pointer to a system-allocated buffer specifying a sorted list of the requested information. The format of this data depends on the value of the Level parameter. Because this buffer is allocated by the system, it must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA. For more information, see the following Return Values section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The Level parameter specifies an invalid value.
ERROR_MORE_DATA | More entries are available. That is, the last entry returned in the SortedBuffer parameter is not the last entry available. To retrieve additional entries, call NetQueryDisplayInformation again with the Index parameter set to the value returned in the next_index member of the last entry in SortedBuffer. Note that you should not use the value of the next_index member for any purpose except to retrieve more data with additional calls to NetQueryDisplayInformation.

Remarks

The NetQueryDisplayInformation and NetGetDisplayInformationIndex functions provide an efficient mechanism for enumerating user and group accounts. When possible, use these functions instead of the NetUserEnum function or the NetGroupEnum function.

To enumerate trusting domains or member computer accounts, call NetUserEnum, specifying the appropriate filter value to obtain the account information you require. To enumerate trusted domains on Windows NT 4.0 and earlier, call the LsaEnumerateTrustedDomains function.

Windows 2000 or later: On Windows 2000, each call to NetQueryDisplayInformation returns a maximum of 100 objects. Calling the NetQueryDisplayInformation function to enumerate account information on a Windows 2000 domain can be costly in terms of performance. If you are programming for Active Directory, you may be able to use methods on the IDirectorySearch interface to make paged queries against the domain. For more information, see IDirectorySearch::SetSearchPreference and IDirectorySearch::ExecuteSearch. To enumerate trusted domains on Windows 2000, call the LsaEnumerateTrustedDomainsEx function.

The following code sample demonstrates how to return group account information using a call to the NetQueryDisplayInformation function. If the user specifies a server name, the sample first calls the MultiByteToWideChar function to convert the name to Unicode. The sample calls NetQueryDisplayInformation, specifying information level 3 (NET_DISPLAY_GROUP) to retrieve group account information. If there are entries to return, the sample returns the data and prints the group information. Finally, the code sample frees the memory allocated for the information buffer.

#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>

void main( int argc, char *argv[ ] )
{
   PNET_DISPLAY_GROUP pBuff, p;
   DWORD res, dwRec, i = 0;
   //
   // You can pass a NULL or empty string
   //  to retrieve the local information.
   //
   TCHAR szServer[255]=TEXT("");

   if(argc > 1)
      //
      // Check to see if a server name was passed;
      //  if so, convert it to Unicode.
      //
      MultiByteToWideChar(CP_ACP, 0, argv[1], -1, szServer, 255);

   do // begin do
   {
      //
      // Call the NetQueryDisplayInformation function;
      //   specify information level 3 (group account information).
      //
      res = NetQueryDisplayInformation(szServer, 3, i, 1000, 0xFFFFFFFF, &dwRec, &pBuff);
      //
      // If the call succeeds,
      //
      if((res==ERROR_SUCCESS) || (res==ERROR_MORE_DATA))
      {
         p = pBuff;
         for(;dwRec>0;dwRec--)
         {
            //
            // Print the retrieved group information.
            //
            printf("Name:      %S\n"
                  "Comment:   %S\n"
                  "Group ID:  %u\n"
                  "Attributs: %u\n"
                  "--------------------------------\n",
                  p->grpi3_name,
                  p->grpi3_comment,
                  p->grpi3_group_id,
                  p->grpi3_attributes);
            //
            // If there is more data, set the index.
            //
            i = p->grpi3_next_index;
            p++;
         }
         //
         // Free the allocated memory.
         //
         NetApiBufferFree(pBuff);
      }
      else
         printf("Error: %u\n", res);
   //
   // Continue while there is more data.
   //
   } while (res==ERROR_MORE_DATA); // end do
   return;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Get Functions, NET_DISPLAY_GROUP, NET_DISPLAY_MACHINE, NET_DISPLAY_USER, NetGetDisplayInformationIndex, NetUserEnum, NetGroupEnum


NetRemoteComputerSupports

The NetRemoteComputerSupports function queries the redirector to retrieve the optional features the remote system supports. Features include Unicode, Remote Procedure Call (RPC), and Remote Administration Protocol support. The function establishes a network connection if one does not exist.

Security Requirements

No special group membership is required to successfully execute the NetRemoteComputerSupports function.

NET_API_STATUS NetRemoteComputerSupports(
  LPCWSTR UncServerName,
  DWORD OptionsWanted,
  LPDWORD OptionsSupported
);

Parameters

UncServerName
[in] Pointer to a constant null-terminated Unicode character string that specifies the name of the remote server to query. The string must begin with \\. If this parameter is NULL, the local computer is used.
OptionsWanted
[in] Specifies a DWORD value that contains a set of bit flags indicating the features of interest. This parameter must be at least one of the following values.
Value | Meaning
SUPPORTS_REMOTE_ADMIN_PROTOCOL | Requests Remote Administration Protocol support.
SUPPORTS_RPC | Requests RPC support.
SUPPORTS_SAM_PROTOCOL | Requests Security Account Manager (SAM) support.
SUPPORTS_UNICODE | Requests Unicode standard support.
SUPPORTS_LOCAL | Requests support for the first three values listed in this table. If UNICODE is defined by the calling application, requests the four features listed previously.

OptionsSupported
[out] Pointer to a DWORD value that receives a set of bit flags. The flags indicate which features specified by the OptionsWanted parameter are implemented on the computer specified by the UncServerName parameter. (All other bits are set to zero.)

The value of this parameter is valid only when the NetRemoteComputerSupports function returns NERR_Success.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | Either the OptionsWanted parameter or the OptionsSupported parameter is NULL; both parameters are required.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmremutl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Remote Utility Functions, NetServerGetInfo


NetRemoteTOD

The NetRemoteTOD function returns the time of day information from a specified server.

Security Requirements

No special group membership is required to successfully execute the NetRemoteTOD function.

NET_API_STATUS NetRemoteTOD(
  LPCWSTR UncServerName,
  LPBYTE *BufferPtr
);

Parameters

UncServerName
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
BufferPtr
[out] Pointer to the address that receives the TIME_OF_DAY_INFO information structure. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The following code sample demonstrates how to retrieve and print the current date and time with a call to the NetRemoteTOD function. To do this, the sample uses the TIME_OF_DAY_INFO structure. Finally, the sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPTIME_OF_DAY_INFO pBuf = NULL;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   //
   // Call the NetRemoteTOD function.
   //
   nStatus = NetRemoteTOD(pszServerName,
                          (LPBYTE *)&pBuf);
   //
   // If the function succeeds, display the current date and time.
   //
   if (nStatus == NERR_Success)
   {
      if (pBuf != NULL)
      {
         fprintf(stderr, "\nThe current date is: %d/%d/%d\n",
                 pBuf->tod_month, pBuf->tod_day, pBuf->tod_year);
         fprintf(stderr, "The current time is: %d:%d:%d\n",
                 pBuf->tod_hours, pBuf->tod_mins, pBuf->tod_secs);
      }
   }
   //
   // Otherwise, display a system error.
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmremutl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Remote Utility Functions, TIME_OF_DAY_INFO


NetRenameMachineInDomain

The NetRenameMachineInDomain function changes the name of a computer in a domain.

Security Requirements

Renaming a domain computer can be performed only by a member of the Administrators local group on the target computer. If you call the NetRenameMachineInDomain function remotely, you must supply credentials because you cannot delegate credentials under these circumstances.

NET_API_STATUS NetRenameMachineInDomain(
  LPCWSTR lpServer,
  LPCWSTR lpNewMachineName,
  LPCWSTR lpAccount,
  LPCWSTR lpPassword,
  DWORD fRenameOptions
);

Parameters

lpServer
[in] Pointer to a constant null-terminated Unicode character string that specifies the name of the computer on which to call the function. If this parameter is NULL, the local computer is used.
lpNewMachineName
[in] Pointer to a constant null-terminated Unicode character string that specifies the new name of the computer. If specified, the local computer name is changed as well. If this parameter is NULL, the function assumes you have already called the SetComputerNameEx function.
lpAccount
[in] Pointer to a constant null-terminated Unicode character string that specifies an account name to use when connecting to the domain controller. If this parameter is NULL, the caller's context is used.
lpPassword
[in] If the lpAccount parameter specifies an account name, this parameter must point to the password to use when connecting to the domain controller. Otherwise, this parameter must be NULL.
fRenameOptions
[in] Specifies the rename options. If this parameter is NETSETUP_ACCT_CREATE, the function renames the account in the domain.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes or one of the Win32 error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter is incorrect.
NERR_SetupNotJoined | The computer is not currently joined to a domain.
NERR_SetupDomainController | This computer is a domain controller and cannot be unjoined from a domain.

Remarks

Different processes, or different threads of the same process, should not call the NetRenameMachineInDomain function at the same time. This situation can leave the computer in an inconsistent state.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmjoin.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, SetComputerNameEx, NetUnjoinDomain


NetReplExportDirAdd

The NetReplExportDirAdd function registers an existing directory in the export path for replication.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Account Operators local group can successfully execute the NetReplExportDirAdd function.

NET_API_STATUS NetReplExportDirAdd(
  LPCWSTR servername,
  DWORD level,
  const LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
1 | Specifies an export subdirectory and its attributes. The buf parameter points to a REPL_EDIR_INFO_1 structure.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first parameter that causes the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

When you add a directory to the export path using a call to the NetReplExportDirAdd function, you must specify the settings for the integrity and extent replication controls. To do this, use the rpedX_integrity and rpedX_extent members of the appropriate REPL_EDIR_INFO structure. The integrity control determines when a master updates a client. The extent control specifies the selection of files for replication within the main export directory. For more information, see replicator export directory functions and REPL_EDIR_INFO_1.

The file replicator service automatically registers a new directory for replication when a user creates it under the master directory's export path. In this case, the file replicator service gives the directory the REPL_INTEGRITY_FILE and REPL_EXTENT_TREE settings for the integrity and extent replication controls.

The default values for locktime and lockcount are both 0. For more information about these values, see REPL_EDIR_INFO_2.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplExportDirDel, REPL_EDIR_INFO_1


NetReplExportDirDel

The NetReplExportDirDel function removes the registration of an export directory for replication.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Account Operators local group can successfully execute the NetReplExportDirDel function.

NET_API_STATUS NetReplExportDirDel(
  LPCWSTR servername,
  LPCWSTR dirname
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the name of a replicated directory to remove from the registration files.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The NetReplExportDirDel function removes the registration of an export directory for replication. To lock a directory so that replication from it can be suspended, you can call the NetReplExportDirLock function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplExportDirAdd


NetReplExportDirEnum

The NetReplExportDirEnum function lists the replicated directories in the export path.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

No special group membership is required to successfully execute the NetReplExportDirEnum function.

NET_API_STATUS NetReplExportDirEnum(
  LPCWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return export subdirectory names. The bufptr parameter points to an array of REPL_EDIR_INFO_0 structures.
1 | Return export subdirectory names and attributes. The bufptr parameter points to an array of REPL_EDIR_INFO_1 structures.
2 | Return export subdirectory names, attributes, and locking information. The bufptr parameter points to an array of REPL_EDIR_INFO_2 structures.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the actual enumerated element count.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resumehandle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing use search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplExportDirGetInfo, REPL_EDIR_INFO_0, REPL_EDIR_INFO_1, REPL_EDIR_INFO_2


NetReplExportDirGetInfo

The NetReplExportDirGetInfo function retrieves the control information for a replicated export directory.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

No special group membership is required to successfully execute the NetReplExportDirGetInfo function.

NET_API_STATUS NetReplExportDirGetInfo(
  LPCWSTR servername,
  LPCWSTR dirname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the export directory name about which to return control information.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the export subdirectory name. The bufptr parameter points to a REPL_EDIR_INFO_0 structure.
1 | Return the export subdirectory name and attributes. The bufptr parameter points to a REPL_EDIR_INFO_1 structure.
2 | Return the export subdirectory name, attributes, and locking information. The bufptr parameter points to a REPL_EDIR_INFO_2 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

To modify the control information for an export directory, call NetReplExportDirSetInfo.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplExportDirSetInfo, NetReplExportDirEnum, REPL_EDIR_INFO_0, REPL_EDIR_INFO_1, REPL_EDIR_INFO_2


NetReplExportDirLock

The NetReplExportDirLock function locks a replicated export directory so that replication from it can be suspended. The function increments the lock reference count for the specified directory.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Account Operators local group can successfully execute the NetReplExportDirLock function.

NET_API_STATUS NetReplExportDirLock(
  LPCWSTR servername,
  LPCWSTR dirname
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the export directory to lock.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The NetReplExportDirLock function locks a directory so that replication from it can be suspended. To remove the registration of an export directory for replication, call the NetReplExportDirDel function.

The rped2_lockcount and rped2_locktime members of the REPL_EDIR_INFO_2 structure contain lock status information. The rped2_locktime member is automatically set to 0 when the rped2_lockcount member is 0.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplExportDirUnlock


NetReplExportDirSetInfo

The NetReplExportDirSetInfo function modifies the control information of a replicated export directory.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Account Operators local group can successfully execute the NetReplExportDirSetInfo function.

NET_API_STATUS NetReplExportDirSetInfo(
  LPCWSTR servername,
  LPCWSTR dirname,
  DWORD level,
  const LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the export directory to return control information about.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
1 | Specifies the export subdirectory name and attributes. The buf parameter points to a REPL_EDIR_INFO_1 structure.
1000 | Specifies a value for the integrity replication control. The buf parameter points to a REPL_EDIR_INFO_1000 structure.
1001 | Specifies a value for the extent replication control. The buf parameter points to a REPL_EDIR_INFO_1001 structure.

For a description of the integrity and extent replication controls, see replicator functions.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first parameter error when the function returns an ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

To modify the current lock count on an export subdirectory you must call the NetReplExportDirLock function or the NetReplExportDirUnlock function. You cannot change the lock count with a call to the NetReplExportDirSetInfo function.

To retrieve the control information for an export directory, call NetReplExportDirGetInfo.

The rped2_lockcount and rped2_locktime members of the REPL_EDIR_INFO_2 structure contain lock status information. The rped2_locktime member is automatically set to 0 when the rped2_lockcount member is 0.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplExportDirGetInfo, REPL_EDIR_INFO_0, REPL_EDIR_INFO_1000, REPL_EDIR_INFO_1001


NetReplExportDirUnlock

The NetReplExportDirUnlock function unlocks an export directory so that replication from it can resume. The function decrements the lock reference count for the specified directory.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Account Operators local group can successfully execute the NetReplExportDirUnlock function.

NET_API_STATUS NetReplExportDirUnlock(
  LPCWSTR servername,
  LPCWSTR dirname,
  DWORD unlockforce
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the directory to unlock.
unlockforce
[in] Specifies a force level to use when unlocking the export directory. This parameter can be one of the following values.
Value | Meaning
REPL_UNLOCK_NOFORCE | Decrements the lock reference count for the export directory. Note that the lock reference count may or may not return to 0, so the directory could remain locked.
REPL_UNLOCK_FORCE | Unlocks the export directory by removing all outstanding locks on the directory. Sets the lock reference count to 0.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Replication resumes when all outstanding locks on the directory are released and the lock reference count is returned to 0.

The rped2_lockcount and rped2_locktime members of the REPL_EDIR_INFO_2 structure contain lock status information. The rped2_locktime member is automatically set to 0 when the rped2_lockcount member is 0.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplExportDirLock


NetReplGetInfo

The NetReplGetInfo function retrieves configuration information for the file replicator service.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

No special group membership is required to successfully execute the NetReplGetInfo function.

NET_API_STATUS NetReplGetInfo(
  LPCWSTR servername,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Return configuration information for the file replicator service. The bufptr parameter points to a REPL_INFO_0 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

You can call the NetReplSetInfo function to modify configuration information for the file replicator service.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplSetInfo, REPL_INFO_0


NetReplImportDirAdd

The NetReplImportDirAdd function registers an existing directory in the import path to receive replication from a master.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Replicator group can successfully execute the NetReplImportDirAdd function.

NET_API_STATUS NetReplImportDirAdd(
  LPCWSTR servername,
  DWORD level,
  const LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Specifies an import subdirectory name. The buf parameter points to a REPL_IDIR_INFO_0 structure.

buf
[in] Pointer to a buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives an index to the first parameter that caused the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The NetReplImportDirAdd function cannot create a directory.

A client directory can be registered for replication in one of the following ways:

  • The file replicator service automatically adds a directory to the client's import path if the directory is exported by a master from which the import server is already importing.
  • An application can call the NetReplImportDirAdd to register a preexisting directory in the import path. This can be useful if you want to modify the import directory's properties prior to importing the directory.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplImportDirDel, REPL_IDIR_INFO_0


NetReplImportDirDel

The NetReplImportDirDel function removes the registration of a directory so that it no longer receives updates from the master. The function does not delete the directory from the file system.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Replicator group can successfully execute the NetReplImportDirDel function.

NET_API_STATUS NetReplImportDirDel(
  LPCWSTR servername,
  LPCWSTR dirname
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the name of a replicated directory to remove the registration.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

To unregister a directory that is no longer being exported, call the NetReplImportDirDel function. However, a call to NetReplImportDirDel does not stop replication of a directory if an exporter is actively exporting the directory. This is because the directory will be registered again the next time the exporter informs the importer of the directories it is exporting. To suspend replication and prevent importing a directory that is actively being exported, call the NetReplImportDirLock function.

The file replicator service can automatically register the directory service at any time.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplImportDirAdd, NetReplImportDirLock


NetReplImportDirEnum

The NetReplImportDirEnum function lists the replicated directories in the import path.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

No special group membership is required to successfully execute the NetReplImportDirEnum function.

NET_API_STATUS NetReplImportDirEnum(
  LPCWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return import subdirectory names. The bufptr parameter points to an array of REPL_IDIR_INFO_0 structures.
1 | Return import subdirectory names and information. The bufptr parameter points to an array of REPL_IDIR_INFO_1 structures.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the actual enumerated element count.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resumehandle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplImportDirGetInfo, REPL_IDIR_INFO_0, REPL_IDIR_INFO_1


NetReplImportDirGetInfo

The NetReplImportDirGetInfo function retrieves status information for a replicated directory on an import server.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

No special group membership is required to successfully execute the NetReplImportDirGetInfo function.

NET_API_STATUS NetReplImportDirGetInfo(
  LPCWSTR servername,
  LPCWSTR dirname,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the directory name about which to return control information.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the import subdirectory name. The bufptr parameter points to a REPL_IDIR_INFO_0 structure.
1 | Return the import subdirectory name, status, and locking information. The bufptr parameter points to a REPL_IDIR_INFO_1 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

The status information for a directory consists of its replication state, the UNC computer name of the master, and the time (in seconds since 00:00:00, January 1, 1970, GMT) when the directory was last updated. For a complete description of this information, see REPL_IDIR_INFO_1.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplImportDirEnum, REPL_IDIR_INFO_0, REPL_IDIR_INFO_1


NetReplImportDirLock

The NetReplImportDirLock function locks a replicated import directory so that replication to it can be suspended. The function increments the lock reference count for the specified directory.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Replicator group can successfully execute the NetReplImportDirLock function.

NET_API_STATUS NetReplImportDirLock(
  LPCWSTR servername,
  LPCWSTR dirname
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the import directory name to lock.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Return Values

The NetReplImportDirLock function locks a directory so that updates to it are suspended. The function does this by incrementing a lock reference count for the directory. To unlock a directory so that replication to it can resume, call the NetReplImportDirUnlock function. Updates to an import directory occur only when all outstanding locks on the directory are released, and the lock reference count is returned to 0.

To remove the registration of an import directory so that it no longer receives updates from the master, call the NetReplImportDirDel function.

The rpid1_lockcount and rpid1_locktime members of the REPL_IDIR_INFO_1 structure contain lock status information. The rpid1_locktime member is automatically set to 0 when the rpid1_lockcount member is 0.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplImportDirUnlock


NetReplImportDirUnlock

The NetReplImportDirUnlock function unlocks an import directory so that replication to it can resume. The function decrements the lock reference count for the specified directory.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators local group or the Replicator group can successfully execute the NetReplImportDirUnlock function.

NET_API_STATUS NetReplImportDirUnlock(
  LPCWSTR servername,
  LPCWSTR dirname,
  DWORD unlockforce
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
dirname
[in] Pointer to a constant null-terminated Unicode string specifying the import directory name to unlock.
unlockforce
[in] Specifies a force level to use when unlocking the import directory. This parameter can be one of the following values.
Value | Meaning
REPL_UNLOCK_NOFORCE | Decrements the lock reference count for the import directory. Note that the lock reference count may or may not return to 0, so the directory could remain locked.
REPL_UNLOCK_FORCE | Unlocks the import directory by removing all outstanding locks on the directory. Sets the lock reference count to 0.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Replication resumes when all outstanding locks on the directory are released and the lock reference count is returned to 0.

The rpid1_lockcount and rpid1_locktime members of the REPL_IDIR_INFO_1 structure contain lock status information. The rpid1_locktime member is automatically set to 0 when the rpid1_lockcount member is 0.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplImportDirLock


NetReplSetInfo

The NetReplSetInfo function modifies the file replicator service configuration information.

Windows NT/2000 or later: Note that the replicator functions work only when the target machine is running Windows NT 4.0 or earlier and the local machine is running Windows 2000 or earlier.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetReplSetInfo function.

NET_API_STATUS NetReplSetInfo(
  LPCWSTR servername,
  DWORD level,
  const LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant null-terminated Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies configuration information for the file replicator service. The buf parameter points to a REPL_INFO_0 structure.
1000 | Specifies the interval that elapses between the times the exporter contacts each import server for changes in each top-level directory. The buf parameter points to a REPL_INFO_1000 structure.
1001 | Specifies a count that the file replicator service uses to synchronize the importer and the exporter. The buf parameter points to a REPL_INFO_1001 structure.
1002 | Specifies the time that each file and directory must be stable before the file replicator service updates the client. The buf parameter points to a REPL_INFO_1002 structure.
1003 | Specifies the maximum time the importer waits before requesting an update from the exporter. The buf parameter points to a REPL_INFO_1003 structure.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first parameter that caused the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

You can call the NetReplGetInfo function to retrieve configuration information for the file replicator service.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Replicator Functions, NetReplGetInfo, REPL_INFO_0, REPL_INFO_1000, REPL_INFO_1001, REPL_INFO_1002, REPL_INFO_1003


NetScheduleJobAdd

The NetScheduleJobAdd function submits a job to run at a specified future time and date. This function requires that the schedule service be started at the computer to which the job is submitted.

Security Requirements

Only members of the Administrators local group can successfully execute the NetScheduleJobAdd function on a remote server.

NET_API_STATUS NetScheduleJobAdd(
  LPCWSTR Servername,
  LPBYTE Buffer,
  LPDWORD JobId
);

Parameters

Servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
Buffer
[in] Pointer to an AT_INFO structure describing the job to submit. For more information about scheduling jobs using different job properties, see the following Remarks section.
JobId
[out] Pointer that receives a job identifier for the newly submitted job. This entry is valid only if the function returns successfully.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Following are examples of how to schedule jobs using different properties supported by the NetScheduleJobAdd function.

To schedule a job that executes once

  • Set the DaysOfMonth member of the AT_INFO structure to zero.
  • Set the DaysOfWeek member to zero.
  • Set the JobTime member to the time the job should execute.

The job executes at the time specified by the JobTime member. After the job executes, it is deleted.

To schedule and delete a job that executes multiple times

  • Set the appropriate bits in the DaysOfMonth member of the AT_INFO structure.
  • Set the appropriate bits in the DaysOfWeek member. (You do not need to set both the DaysOfMonth and the DaysOfWeek members.)
  • Set the JobTime member to the time the job should execute.

The job executes at the time specified by the JobTime member, once for each day set in DaysOfMonth and DaysOfWeek. After each execution, the corresponding bit is cleared. When the last bit is cleared, the job is deleted.

To schedule a job that executes periodically

  • Set the appropriate bits in the DaysOfMonth member of the AT_INFO structure.
  • Set the appropriate bits in the DaysOfWeek member. (You do not need to set both the DaysOfMonth and the DaysOfWeek members.)
  • Set the JobTime member to the time the job should execute.
  • Set the job submission flag JOB_RUN_PERIODICALLY in the Flags member.

The job will execute periodically, at the time specified by the JobTime member, on each day set in DaysOfMonth and DaysOfWeek. The job will not be deleted as a result of the repeated executions. The only way to delete the job is by an explicit call to the NetScheduleJobDel function.

See AT_INFO for a description of the DaysOfWeek, DaysOfMonth, and job property bitmasks.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmat.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Schedule Functions, AT_INFO, NetScheduleJobDel, NetScheduleJobEnum


NetScheduleJobDel

The NetScheduleJobDel function deletes a range of jobs queued to run at a computer. This function requires that the schedule service be started at the computer to which the job deletion request is being sent.

Security Requirements

Only members of the Administrators local group can successfully execute the NetScheduleJobDel function on a remote server.

NET_API_STATUS NetScheduleJobDel(
  LPCWSTR Servername,
  DWORD MinJobId,
  DWORD MaxJobId
);

Parameters

Servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
MinJobId
[in] Specifies a minimum job identifier. Jobs with a job identifier smaller than MinJobId will not be deleted.
MaxJobId
[in] Specifies a maximum job identifier. Jobs with a job identifier larger than MaxJobId will not be deleted.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Call the NetScheduleJobEnum function to retrieve the job identifier for one or more scheduled jobs.

The NetScheduleJobDel function deletes all jobs whose job identifiers are in the range MinJobId through MaxJobId.

To delete all scheduled jobs at the server, you can call NetScheduleJobDel specifying MinJobId equal to 0 and MaxJobId equal to – 1. To delete one job, specify the job's identifier for both the MinJobId parameter and the MaxJobId parameter.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmat.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Schedule Functions, NetScheduleJobAdd, NetScheduleJobEnum


NetScheduleJobEnum

The NetScheduleJobEnum function lists the jobs queued on a specified computer. This function requires that the schedule service be started.

Security Requirements

Only members of the Administrators local group can successfully execute the NetScheduleJobEnum function on a remote server.

NET_API_STATUS NetScheduleJobEnum(
  LPCWSTR Servername,
  LPBYTE *PointerToBuffer,
  DWORD PreferredMaximumLength,
  LPDWORD EntriesRead,
  LPDWORD TotalEntries,
  LPDWORD ResumeHandle
);

Parameters

Servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
PointerToBuffer
[out] Pointer to the buffer that receives the data. The return information is an array of AT_ENUM structures. The buffer is allocated by the system and must be freed using a single call to the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
PreferredMaximumLength
[in] Specifies a DWORD value that indicates the preferred maximum length of the returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
EntriesRead
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
TotalEntries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
ResumeHandle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue a job enumeration. The handle should be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Each entry returned contains an AT_ENUM structure. The value of the JobId member can be used when calling functions that require a job identifier parameter, such as the NetScheduleJobDel function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmat.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Schedule Functions, AT_ENUM, NetScheduleJobDel, NetScheduleJobGetInfo


NetScheduleJobGetInfo

The NetScheduleJobGetInfo function retrieves information about a particular job queued on a specified computer. This function requires that the schedule service be started.

Security Requirements

Only members of the Administrators local group can successfully execute the NetScheduleJobGetInfo function on a remote server.

NET_API_STATUS NetScheduleJobGetInfo(
  LPCWSTR Servername,
  DWORD JobId,
  LPBYTE *PointerToBuffer
);

Parameters

Servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
JobId
[in] Specifies a DWORD value that indicates the identifier of the job for which to retrieve information.
PointerToBuffer
[out] Pointer to the buffer that receives the AT_INFO structure describing the specified job. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmat.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Schedule Functions, AT_INFO, NetScheduleJobEnum


NetSecurityGetInfo

Windows 95/98/Me: The NetSecurityGetInfo function retrieves the specified level of access control information.

Windows NT/2000 or later: This function is not supported on Windows NT/Windows 2000.

Security Requirements

When this function executes locally, no special privilege is required.

extern API_FUNCTION
 NetSecurityGetInfo(
  const char FAR * pszServer,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short  cbBuffer,
  unsigned short FAR * pcbTotalAvail
);

Parameters

pszServer
Pointer to an ASCIIZ string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
sLevel
Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
1 | The pbBuffer parameter points to a security_info_1 structure.

pbBuffer
Pointer to the buffer that receives the security information structure.
cbBuffer
Specifies the size, in bytes, of the buffer pointed to by the pbBuffer parameter.
pcbTotalAvail
Pointer to an unsigned short integer that receives the total number of entries available.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

Windows 95/98/Me: See the NetSecurityGetInfo Sample (Windows 95/98) topic to view a code sample that demonstrates how to call the NetSecurityGetInfo function.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.
Library: Use Svrapi.lib.

See Also

Network Management Overview, Network Management Functions, security_info_1, NetAccessGetInfo


NetServerComputerNameAdd

The NetServerComputerNameAdd function enumerates the transports on which the specified server is active, and binds the emulated server name to each of the transports.

NetServerComputerNameAdd is a utility function that combines the functionality of the NetServerTransportEnum function and the NetServerTransportAddEx function.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetServerComputerNameAdd function.

NET_API_STATUS NetServerComputerNameAdd(
  LPWSTR ServerName,
  LPWSTR EmulatedDomainName,
  LPWSTR EmulatedServerName
);

Parameters

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
EmulatedDomainName
[in] Pointer to a null-terminated Unicode character string that contains the domain name the specified server should use when announcing its presence using the EmulatedServerName. This parameter is optional.
EmulatedServerName
[in] Pointer to a null-terminated character string that contains the emulated name the server should begin supporting in addition to the name specified by the ServerName parameter.

Return Values

If the function succeeds, the return value is NERR_Success. Note that NetServerComputerNameAdd succeeds if the emulated server name specified is added to at least one transport.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_DUP_NAME | A duplicate name exists on the network.
ERROR_INVALID_DOMAINNAME | The domain name could not be found on the network.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

Remarks

The server specified by the ServerName parameter continues to support all names it was supporting, and additionally begins to support new names supplied by successful calls to the NetServerComputerNameAdd function.

Name emulation that results from a call to NetServerComputerNameAdd ceases when the server reboots or restarts. To discontinue name emulation set by a previous call to NetServerComputerNameAdd without restarting or rebooting, you can call the NetServerComputerNameDel function.

The NetServerComputerNameAdd function is typically used when a system administrator replaces a server, but wants to keep the conversion transparent to users. Following is an example of a call to the NetServerComputerNameAdd function requesting that \\Server1 also respond to requests for \\Server2.

NetServerComputerNameAdd (Server1, NULL, Server2);

For more information about registry settings that result in persistent emulations, see the Windows 2000 resource kits.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server Functions, NetServerTransportEnum, NetServerTransportAdd, NetServerTransportAddEx, NetServerComputerNameDel


NetServerComputerNameDel

The NetServerComputerNameDel function causes the specified server to cease supporting the emulated server name set by a previous call to the NetServerComputerNameAdd function. The function does this by unbinding network transports from the emulated name.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetServerComputerNameDel function.

NET_API_STATUS NetServerComputerNameDel(
  LPWSTR ServerName,
  LPWSTR EmulatedServerName
);

Parameters

ServerName
[in] Pointer to a null-terminated Unicode character string that specifies the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
EmulatedServerName
[in] Pointer to a null-terminated character string that contains the emulated name the server should stop supporting. The server continues to support all other server names it was supporting.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_NetNameNotFound | The share name does not exist.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server Functions, NetServerComputerNameAdd, NetServerTransportEnum, NetServerTransportAdd, NetServerTransportAddEx


NetServerDiskEnum

The NetServerDiskEnum function retrieves a list of disk drives on a server. The function returns an array of three-character strings (a drive letter, a colon, and a terminating null character).

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetServerDiskEnum function on a remote computer. No special group membership is required for local calls.

NET_API_STATUS NetServerDiskEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] This parameter must be zero.
bufptr
[out] Pointer to the buffer that receives the data. The data is an array of three-character strings (a drive letter, a colon, and a terminating null character). This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resume_handle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing server disk search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

Remarks

The following code sample demonstrates how to call the NetServerDiskEnum function to retrieve a list of disk drives on a server. The sample calls NetServerDiskEnum, specifying the information level 0 (required). If there are entries to return, and the user has access to the information, it prints a list of the drives, in the format of a three-character string: a drive letter, a colon, and a terminating null character. The sample also prints the total number of entries that are available and the number of entries actually enumerated. Finally, the code sample frees the memory allocated for the buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   const int ENTRY_SIZE = 3; // Drive letter, colon, NULL
   LPTSTR pBuf = NULL;
   DWORD dwLevel = 0; // level must be zero
   DWORD dwPrefMaxLen = -1;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   //
   // Call the NetServerDiskEnum function.
   //
   nStatus = NetServerDiskEnum(pszServerName,
                               dwLevel,
                               (LPBYTE *) &pBuf,
                               dwPrefMaxLen,
                               &dwEntriesRead,
                               &dwTotalEntries,
                               NULL);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPTSTR pTmpBuf;

      if ((pTmpBuf = pBuf) != NULL)
      {
         DWORD i;
         DWORD dwTotalCount = 0;
         //
         // Loop through the entries.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               // On a remote computer, only members of the
               //  Administrators or the Account Operators
               //  local group can execute NetServerDiskEnum.
               //
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }
            //
            // Print drive letter, colon, NULL for each drive;
            //   the number of entries actually enumerated; and
            //   the total number of entries available.
            //
            fwprintf(stdout, L"\tDisk: %S\n", pTmpBuf);

            pTmpBuf += ENTRY_SIZE;
            dwTotalCount++;
         }

         fprintf(stderr, "\nEntries enumerated: %d\n", dwTotalCount);
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

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 server functions. For more information, see IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server Functions, NetServerEnum


NetServerEnum

The NetServerEnum function lists all servers of the specified type that are visible in a domain. For example, an application can call NetServerEnum to list all domain controllers only or all SQL servers only.

You can combine bit masks to list several types. For example, a value of 0x00000003 combines the bit masks for SV_TYPE_WORKSTATION (0x00000001) and SV_TYPE_SERVER (0x00000002).

If you require more information for a specific server, call the WNetEnumResource function.

Security Requirements

No special group membership is required to successfully execute the NetServerEnum function.

NET_API_STATUS NetServerEnum(
  LPCWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  DWORD servertype,
  LPCWSTR domain,
  LPDWORD resume_handle
);

Parameters

servername
[in] Reserved; must be NULL.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
100 | Return server names and platform information. The bufptr parameter points to an array of SERVER_INFO_100 structures.
101 | Return server names, types, and associated software. The bufptr parameter points to an array of SERVER_INFO_101 structures.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of visible servers and workstations on the network.
servertype
[in] Specifies a DWORD value that filters the server entries to return from the enumeration. This parameter can be one or more of the following values.
Value | Meaning
SV_TYPE_WORKSTATION | All workstations
SV_TYPE_SERVER | All servers
SV_TYPE_SQLSERVER | Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL | Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL | Backup domain controller
SV_TYPE_TIME_SOURCE | Server running the Timesource service
SV_TYPE_AFP | Apple File Protocol servers
SV_TYPE_NOVELL | Novell servers
SV_TYPE_DOMAIN_MEMBER | LAN Manager 2.x domain member
SV_TYPE_LOCAL_LIST_ONLY | Servers maintained by the browser. See the following Remarks section.
SV_TYPE_PRINTQ_SERVER | Server sharing print queue
SV_TYPE_DIALIN_SERVER | Server running dial-in service
SV_TYPE_XENIX_SERVER | Xenix server
SV_TYPE_SERVER_MFPN | Microsoft File and Print for NetWare
SV_TYPE_NT | Windows NT/Windows 2000 workstation or server
SV_TYPE_WFW | Server running Windows for Workgroups
SV_TYPE_SERVER_NT | Windows NT/Windows 2000 server that is not a domain controller
SV_TYPE_POTENTIAL_BROWSER | Server that can run the browser service
SV_TYPE_BACKUP_BROWSER | Server running a browser service as backup
SV_TYPE_MASTER_BROWSER | Server running the master browser service
SV_TYPE_DOMAIN_MASTER | Server running the domain master browser
SV_TYPE_DOMAIN_ENUM | Primary domain
SV_TYPE_WINDOWS | Windows 95 or later
SV_TYPE_ALL | All servers
SV_TYPE_TERMINALSERVER | Terminal Server
SV_TYPE_CLUSTER_NT | Server clusters available in the domain
SV_TYPE_CLUSTER_VS_NT | Whistler: Cluster virtual servers available in the domain

domain
[in] Pointer to a constant Unicode string specifying the name of the domain for which a list of servers is to be returned. The domain name must be a NetBIOS domain name (for example, microsoft). NetServerEnum does not support DNS-style names (for example, microsoft.com). If this parameter is NULL, the primary domain is implied.
resume_handle
Reserved; must be set to zero.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes:

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_NO_BROWSER_SERVERS_FOUND | No browser servers found.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.

Remarks

If you specify the value SV_TYPE_LOCAL_LIST_ONLY, the NetServerEnum function returns the list of servers that the browser maintains internally. This has meaning only on the master browser (or on a computer that has been the master browser in the past). The master browser is the machine that currently has rights to determine which machines can be servers or workstations on the network.

The following code sample demonstrates how to list all servers that are visible in the primary domain with a call to the NetServerEnum function. The sample calls NetServerEnum, specifying information level 101 (SERVER_INFO_101). The sample code loops through the entries and prints the retrieved data. If the server is a domain controller, it identifies the server as either a primary domain controller (PDC) or a backup domain controller (BDC). The sample also prints the total number of entries available and the number of entries actually enumerated, warning the user if all entries were not enumerated. Finally, the sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPSERVER_INFO_101 pBuf = NULL;
   LPSERVER_INFO_101 pTmpBuf;
   DWORD dwLevel = 101;
   DWORD dwPrefMaxLen = -1;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwTotalCount = 0;
   DWORD dwServerType = SV_TYPE_SERVER; // all servers
   DWORD dwResumeHandle = 0;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;
   DWORD i;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   //
   // Call the NetServerEnum function to retrieve information
   //  for all servers, specifying information level 101.
   //
   nStatus = NetServerEnum(pszServerName,
                           dwLevel,
                           (LPBYTE *) &pBuf,
                           dwPrefMaxLen,
                           &dwEntriesRead,
                           &dwTotalEntries,
                           dwServerType,
                           NULL,
                           &dwResumeHandle);
   //
   // If the call succeeds,
   //
   if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
   {
      if ((pTmpBuf = pBuf) != NULL)
      {
         //
         // Loop through the entries and
         //  print the data for all server types.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }

            printf("\tPlatform: %d\n", pTmpBuf->sv101_platform_id);
            wprintf(L"\tName:     %s\n", pTmpBuf->sv101_name);
            printf("\tVersion:  %d.%d\n",
                   pTmpBuf->sv101_version_major,
                   pTmpBuf->sv101_version_minor);
            printf("\tType:     %d", pTmpBuf->sv101_type);
            //
            // Check to see if the server is a domain controller;
            //  if so, identify it as a PDC or a BDC.
            //
            if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_CTRL)
               wprintf(L" (PDC)");
            else if (pTmpBuf->sv101_type & SV_TYPE_DOMAIN_BAKCTRL)
               wprintf(L" (BDC)");

            printf("\n");
            //
            // Also print the comment associated with the server.
            //
            wprintf(L"\tComment:  %s\n\n", pTmpBuf->sv101_comment);

            pTmpBuf++;
            dwTotalCount++;
         }
         // Display a warning if all available entries were
         //  not enumerated, print the number actually
         //  enumerated, and the total number available.

         if (nStatus == ERROR_MORE_DATA)
         {
            fprintf(stderr, "\nMore entries available!!!\n");
            fprintf(stderr, "Total entries: %d", dwTotalEntries);
         }

         printf("\nEntries enumerated: %d\n", dwTotalCount);
      }
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

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 server functions. For more information, see IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server Functions, NetServerDiskEnum, NetQueryDisplayInformation, SERVER_INFO_100, SERVER_INFO_101


NetServerGetInfo

The NetServerGetInfo function retrieves current configuration information for the specified server.

Security Requirements

Only the Administrators or Accounts Operators local group, or those with Communication, Print, or Server operator group membership can successfully execute the NetServerGetInfo function at level 102. No special group membership is required for level 100 or level 101 calls.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetServerGetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr
);

Windows 95/98/Me: The calling application must use the cbBuffer parameter to specify the size, in bytes, of the information buffer pointed to by the pbBuffer parameter. If the length of the buffer is not large enough to hold all of the data, the function returns as much as will fit in the buffer. The function returns the total number of bytes of information available in the pcbTotalAvail parameter. The parameter list is as follows.

extern API_FUNCTION
 NetServerGetInfo(
  const char FAR * pszServer,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short cbBuffer,
  unsigned short FAR * pcbTotalAvail
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.

Windows NT/2000 or later: The following levels are valid on all platforms.
Value | Meaning
100 | Return the server name and platform information. The bufptr parameter points to a SERVER_INFO_100 structure.
101 | Return the server name, type, and associated software. The bufptr parameter points to a SERVER_INFO_101 structure.
102 | Return the server name, type, associated software, and other attributes. The bufptr parameter points to a SERVER_INFO_102 structure.

Windows 95/98/Me: The following levels are valid.
Value | Meaning
1 | Return the server name, type, and associated software. The pbBuffer parameter points to a server_info_1 structure.
50 | Return the server name, type, associated software, and other attributes. The pbBuffer parameter points to a server_info_50 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter.

Windows NT/2000 or later: This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Windows 95/98/Me: The caller must allocate and deallocate this buffer.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

Remarks

Windows 95/98/Me: See the NetServerGetInfo Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetServerGetInfo function.

Windows NT/2000 or later: The following code sample demonstrates how to retrieve current configuration information for a server using a call to the NetServerGetInfo function. The sample calls NetServerGetInfo, specifying information level 101 (SERVER_INFO_101). If the call succeeds, the code attempts to identify the type of server. Finally, the sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 101;
   LPSERVER_INFO_101 pBuf = NULL;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   //
   // Call the NetServerGetInfo function, specifying level 101.
   //
   nStatus = NetServerGetInfo(pszServerName,
                              dwLevel,
                              (LPBYTE *)&pBuf);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      //
      // Check for the type of server.
      //
      if ((pBuf->sv101_type & SV_TYPE_DOMAIN_CTRL) ||
         (pBuf->sv101_type & SV_TYPE_DOMAIN_BAKCTRL) ||
         (pBuf->sv101_type & SV_TYPE_SERVER_NT))
         printf("This is a server\n");
      else
         printf("This is a workstation\n");
   }
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

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 server functions. For more information, see IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmserver.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Server Functions, NetServerSetInfo, SERVER_INFO_100, SERVER_INFO_101, SERVER_INFO_102, server_info_1, server_info_50, NetRemoteComputerSupports


NetServerSetInfo

The NetServerSetInfo function sets a server's operating parameters; it can set them individually or collectively. The information is stored in a way that allows it to remain in effect after the system has been reinitialized.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetServerSetInfo function.

NET_API_STATUS NetServerSetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD ParmError
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
101 | Specifies the server name, type, and associated software. The buf parameter points to a SERVER_INFO_101 structure.
102 | Specifies the server name, type, associated software, and other attributes. The buf parameter points to a SERVER_INFO_102 structure.
402 | Specifies detailed information about the server. The buf parameter points to a SERVER_INFO_402 structure.
403 | Specifies detailed information about the server. The buf parameter points to a SERVER_INFO_403 structure.

In addition, levels 1001-1006, 1009-1011, 1016-1018, 1021, 1022, 1028, 1029, 1037, and 1043 are valid based on the restrictions for LAN Manager systems.

buf
[in] Pointer to a buffer that receives the server information. The format of this data depends on the value of the level parameter.
ParmError
[out] Pointer to a DWORD value that receives the index of the first member of the server information structure that causes the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid. For more information, see the following Remarks section.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

Remarks

See the end of this Remarks section for a code sample that demonstrates use of the NetServerSetInfo function.

If the NetServerSetInfo function returns ERROR_INVALID_PARAMETER, you can use the ParmError parameter to indicate the first member of the server information structure that is invalid. (A server information structure begins with SERVER_INFO_ and its format is specified by the level parameter.) The following table lists the values that can be returned in the ParmError parameter and the corresponding structure member that is in error. (The prefix sv*_ indicates that the member can begin with multiple prefixes, for example, sv101_ or sv402_.)

Value | Member
SV_PLATFORM_ID_PARMNUM | sv*_platform_id
SV_NAME_PARMNUM | sv*_name
SV_VERSION_MAJOR_PARMNUM | sv*_version_major
SV_VERSION_MINOR_PARMNUM | sv*_version_minor
SV_TYPE_PARMNUM | sv*_type
SV_COMMENT_PARMNUM | sv*_comment
SV_USERS_PARMNUM | sv*_users
SV_DISC_PARMNUM | sv*_disc
SV_HIDDEN_PARMNUM | sv*_hidden
SV_ANNOUNCE_PARMNUM | sv*_announce
SV_ANNDELTA_PARMNUM | sv*_anndelta
SV_USERPATH_PARMNUM | sv*_userpath
SV_ULIST_MTIME_PARMNUM | sv*_ulist_mtime
SV_GLIST_MTIME_PARMNUM | sv*_glist_mtime
SV_ALIST_MTIME_PARMNUM | sv*_alist_mtime
SV_ALERTS_PARMNUM | sv*_alerts
SV_SECURITY_PARMNUM | sv*_security
SV_NUMADMIN_PARMNUM | sv*_numadmin
SV_LANMASK_PARMNUM | sv*_lanmask
SV_GUESTACC_PARMNUM | sv*_guestacc
SV_CHDEVQ_PARMNUM | sv*_chdevq
SV_CHDEVJOBS_PARMNUM | sv*_chdevjobs
SV_CONNECTIONS_PARMNUM | sv*_connections
SV_SHARES_PARMNUM | sv*_shares
SV_OPENFILES_PARMNUM | sv*_openfiles
SV_SESSOPENS_PARMNUM | sv*_sessopens
SV_SESSVCS_PARMNUM | sv*_sessvcs
SV_SESSREQS_PARMNUM | sv*_sessreqs
SV_OPENSEARCH_PARMNUM | sv*_opensearch
SV_ACTIVELOCKS_PARMNUM | sv*_activelocks
SV_NUMREQBUF_PARMNUM | sv*_numreqbuf
SV_SIZREQBUF_PARMNUM | sv*_sizreqbuf
SV_NUMBIGBUF_PARMNUM | sv*_numbigbuf
SV_NUMFILETASKS_PARMNUM | sv*_numfiletasks
SV_ALERTSCHED_PARMNUM | sv*_alertsched
SV_ERRORALERT_PARMNUM | sv*_erroralert
SV_LOGONALERT_PARMNUM | sv*_logonalert
SV_ACCESSALERT_PARMNUM | sv*_accessalert
SV_DISKALERT_PARMNUM | sv*_diskalert
SV_NETIOALERT_PARMNUM | sv*_netioalert
SV_MAXAUDITSZ_PARMNUM | sv*_maxauditsz
SV_SRVHEURISTICS_PARMNUM | sv*_srvheuristics
SV_TIMESOURCE_PARMNUM | sv*_timesource

The following code sample demonstrates how to set the comment associated with a server using a call to the NetServerSetInfo function, specifying information level 1005 (SERVER_INFO_1005).

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 1005;
   SERVER_INFO_1005 si;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName Comment\n", argv[0]);
      exit(1);
   }
   //
   // Fill in SERVER_INFO_1005 structure member.
   //
   si.sv1005_comment = argv[2];
   //
   // Call the NetServerSetInfo function,
   //  specifying level 1005.
   //
   nStatus = NetServerSetInfo(argv[1],
                              dwLevel,
                              (LPBYTE)&si,
                              NULL);
   //
   // Display the result of the call.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Comment reset\n", argv[2]);
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

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 server functions. For more information, see IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server Functions, NetServerGetInfo, SERVER_INFO_101, SERVER_INFO_102, SERVER_INFO_402, SERVER_INFO_403


NetServerTransportAdd

The NetServerTransportAdd function binds the server to the transport protocol.

The extended function NetServerTransportAddEx allows the calling application to specify the SERVER_TRANSPORT_INFO_1, SERVER_TRANSPORT_INFO_2, and SERVER_TRANSPORT_INFO_3 information levels.

Security Requirements

Only members of the Administrators local group can successfully execute the NetServerTransportAdd function.

NET_API_STATUS NetServerTransportAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE bufptr
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Specifies information about the transport protocol, including name, address, and location on the network. The bufptr parameter points to a SERVER_TRANSPORT_INFO_0 structure.

bufptr
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_DUP_NAME | A duplicate name exists on the network.
ERROR_INVALID_DOMAINNAME | The domain name could not be found on the network.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server and Workstation Transport Functions, NetServerTransportDel, NetServerTransportAddEx, SERVER_TRANSPORT_INFO_0


NetServerTransportAddEx

The NetServerTransportAddEx function binds the specified server to the transport protocol. This extended function allows the calling application to specify the SERVER_TRANSPORT_INFO_1, SERVER_TRANSPORT_INFO_2, and SERVER_TRANSPORT_INFO_3 information levels.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetServerTransportAddEx function.

NET_API_STATUS NetServerTransportAddEx(
  LPSTR servername,
  DWORD level,
  LPBYTE bufptr
);

Parameters

servername
[in] Pointer to a null-terminated character string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies a DWORD value that indicates the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies information about the transport protocol, including name, address, and location on the network. The bufptr parameter points to a SERVER_TRANSPORT_INFO_0 structure.
1 | Specifies information about the transport protocol, including name, address, network location, and domain. The bufptr parameter points to a SERVER_TRANSPORT_INFO_1 structure.
2 | Specifies the same information as level 1, with the addition of an svti2_flags member. The bufptr parameter points to a SERVER_TRANSPORT_INFO_2 structure.
3 | Windows 2000 or later: Specifies the same information as level 2, with the addition of credential information. The bufptr parameter points to a SERVER_TRANSPORT_INFO_3 structure.

bufptr
[in] Pointer to the buffer that contains the data. The format of this data depends on the value of the level parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_DUP_NAME | A duplicate name exists on the network.
ERROR_INVALID_DOMAINNAME | The domain name could not be found on the network.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.

Remarks

If you add a transport protocol to a server using a call to the NetServerTransportAddEx function, the connection will not remain after the server reboots or restarts.

The NetServerComputerNameAdd function is a utility function. It combines the functionality of the NetServerTransportEnum function and the NetServerTransportAddEx function, allowing you to specify an emulated server name.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server and Workstation Transport Functions, NetServerTransportEnum, NetServerTransportAdd, NetServerComputerNameAdd, NetServerComputerNameDel, NetServerTransportDel, SERVER_TRANSPORT_INFO_0, SERVER_TRANSPORT_INFO_1, SERVER_TRANSPORT_INFO_2, SERVER_TRANSPORT_INFO_3


NetServerTransportDel

The NetServerTransportDel function unbinds (or disconnects) the transport protocol from the server. Effectively, the server can no longer communicate with clients using the specified transport protocol (such as TCP or XNS).

Security Requirements

Only members of the Administrators local group can successfully execute the NetServerTransportDel function.

NET_API_STATUS NetServerTransportDel(
  LPWSTR servername,
  DWORD level,
  LPBYTE bufptr
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies information about the transport protocol, including name, address, and location on the network. The bufptr parameter points to a SERVER_TRANSPORT_INFO_0 structure.
1 | Specifies information about the transport protocol, including name, address, network location, and domain. The bufptr parameter points to a SERVER_TRANSPORT_INFO_1 structure.

bufptr
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_NetNameNotFound | The share name does not exist.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server and Workstation Transport Functions, NetServerTransportAdd, SERVER_TRANSPORT_INFO_0, SERVER_TRANSPORT_INFO_1


NetServerTransportEnum

The NetServerTransportEnum function supplies information about transport protocols that are managed by the server.

Security Requirements

Windows NT/2000: No special group membership is required to successfully execute the NetServerTransportEnum function.

Whistler: Only Authenticated Users can successfully call this function on servers running Whistler and later.

NET_API_STATUS NetServerTransportEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return information about the transport protocol, including name, address, and location on the network. The bufptr parameter points to an array of SERVER_TRANSPORT_INFO_0 structures.
1 | Return information about the transport protocol, including name, address, network location, and domain. The bufptr parameter points to an array of SERVER_TRANSPORT_INFO_1 structures.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resumehandle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing server transport search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.

Remarks

The following code sample demonstrates how to retrieve information about transport protocols that are managed by the server, using a call to the NetServerTransportEnum function. The sample calls NetServerTransportEnum, specifying information level 0 (SERVER_TRANSPORT_INFO_0). The sample prints the name of each transport protocol and the total number enumerated. Finally, the code sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPSERVER_TRANSPORT_INFO_0 pBuf = NULL;
   LPSERVER_TRANSPORT_INFO_0 pTmpBuf;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = 256;//-1
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD dwTotalCount = 0;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;
   DWORD i;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   //
   // Call the NetServerTransportEnum function; specify level 0.
   //
   do // begin do
   {
      nStatus = NetServerTransportEnum(pszServerName,
                                       dwLevel,
                                       (LPBYTE *) &pBuf,
                                       dwPrefMaxLen,
                                       &dwEntriesRead,
                                       &dwTotalEntries,
                                       &dwResumeHandle);
      //
      // If the call succeeds,
      //
      if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
      {
         if ((pTmpBuf = pBuf) != NULL)
         {
            //
            // Loop through the entries;
            //  process access errors.
            //
            for (i = 0; i < dwEntriesRead; i++)
            {
               assert(pTmpBuf != NULL);

               if (pTmpBuf == NULL)
               {
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               // Print the transport protocol name.
               //
               wprintf(L"\tTransport: %s\n", pTmpBuf->svti0_transportname);

               pTmpBuf++;
               dwTotalCount++;
            }
         }
      }
      //
      // Otherwise, indicate a system error.
      //
      else
         fprintf(stderr, "A system error has occurred: %d\n", nStatus);

      //
      // Free the allocated buffer.
      //
      if (pBuf != NULL)
      {
         NetApiBufferFree(pBuf);
         pBuf = NULL;
      }
   //
   // Continue to call NetServerTransportEnum while
   //  there are more entries.
   //
   }
   while (nStatus == ERROR_MORE_DATA); // end do

   // Check again for an allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of transports enumerated.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server and Workstation Transport Functions, SERVER_TRANSPORT_INFO_0, SERVER_TRANSPORT_INFO_1


NetServiceControl

The NetServiceControl function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the service functions.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmsvc.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetServiceEnum

The NetServiceEnum function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the service functions.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmsvc.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetServiceGetInfo

The NetServiceGetInfo function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the service functions.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmsvc.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetServiceInstall

The NetServiceInstall function is obsolete. It is included for compatibility with 16-bit versions of Windows. Win32-based applications should use the service functions.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmsvc.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetSessionDel

The NetSessionDel function ends a network session between a server and a workstation.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetSessionDel function.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetSessionDel(
  LPWSTR servername,
  LPWSTR UncClientName,
  LPWSTR username
);

Windows 95/98/Me: The sReserved parameter replaces the Windows NT/Windows 2000 username parameter. For more information, see the following Remarks section. The parameter list is as follows.

extern API_FUNCTION
 NetSessionDel(
  const char FAR *pszServer,
  const char FAR *pszClientName,
  short  sReserved
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
UncClientName
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the computer name of the client to disconnect. If UncClientName is NULL, then all the sessions of the user identified by the username parameter will be deleted on the server specified by servername. For more information, see NetSessionEnum.
username
[in] Pointer to a Unicode string specifying the name of the user whose session is to be terminated. If this parameter is NULL, all users' sessions from the client specified by the UncClientName parameter are to be terminated.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_ClientNameNotFound | A session does not exist with that computer name.

Remarks

Windows 95/98/Me: You must specify the session key in the sReserved parameter when you call NetSessionDel. The session key is returned by the NetSessionEnum function or the NetSessionGetInfo function in the sesi50_key member of the session_info_50 structure. See the NetSessionDel Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetSessionDel function.

Windows NT/2000 or later: The following code sample demonstrates how to terminate a session between a server and a workstation using a call to the NetSessionDel function.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwError = 0;
   LPTSTR pszServerName = NULL;
   LPTSTR pszClientName = NULL;
   LPTSTR pszUserName = NULL;
   NET_API_STATUS nStatus;
   //
   // Check command line arguments.
   //
   if (argc > 4)
   {
      wprintf(L"Usage: %s [\\\\ServerName] [\\\\ClientName] [UserName]\n", argv[0]);
      exit(1);
   }

   if (argc >= 2)
      pszServerName = argv[1];

   if (argc >= 3)
      pszClientName = argv[2];

   if (argc == 4)
      pszUserName = argv[3];
   //
   // Call the NetSessionDel function to delete the session.
   //
   nStatus = NetSessionDel(pszServerName,
                           pszClientName,
                           pszUserName);
   //
   // Display the result of the call.
   //
   if (nStatus == NERR_Success)
      fprintf(stderr, "The specified session(s) has been successfully deleted\n");
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

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. For more information, see IADsSession and IADsFileServiceOperations.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Session Functions, NetSessionEnum, NetSessionGetInfo, session_info_50


NetSessionEnum

The NetSessionEnum function provides information about sessions established on a server.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetSessionEnum function at level 1 or level 2. No special group membership is required for level 0 or level 10 calls.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetSessionEnum(
  LPWSTR servername,
  LPWSTR UncClientName,
  LPWSTR username,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Windows 95/98/Me: The calling application must use the cbBuffer parameter to specify the size, in bytes, of the information buffer pointed to by the pbBuffer parameter. (The cbBuffer parameter replaces the Windows NT/Windows 2000 prefmaxlen parameter.) Neither a user name parameter nor a resume handle parameter is available on this platform. Therefore, the parameter list is as follows.

extern API_FUNCTION
 NetSessionEnum(
  const char FAR * pszServer,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short  cbBuffer,
  unsigned short FAR * pcEntriesRead,
  unsigned short FAR * pcTotalAvail
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
UncClientName
[in] Pointer to a Unicode string specifying the name of the computer session for which information is to be returned. If this parameter is NULL, NetSessionEnum returns information for all computer sessions on the server.
username
[in] Pointer to a Unicode string specifying the name of the user for which information is to be returned. If this parameter is NULL, NetSessionEnum returns information for all users.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.

Windows NT/2000 or later: The following levels are valid.
Value | Meaning
0 | Return the name of the computer that established the session. The bufptr parameter points to an array of SESSION_INFO_0 structures.
1 | Return the name of the computer, name of the user, and open files, pipes, and devices on the computer. The bufptr parameter points to an array of SESSION_INFO_1 structures.
2 | In addition to the information indicated for level 1, return the type of client and how the user established the session. The bufptr parameter points to an array of SESSION_INFO_2 structures.
10 | Return the name of the computer, name of the user, and active and idle times for the session. The bufptr parameter points to an array of SESSION_INFO_10 structures.
502 | Return the name of the computer; name of the user; open files, pipes, and devices on the computer; and the name of the transport the client is using. The bufptr parameter points to an array of SESSION_INFO_502 structures.

Windows 95/98/Me: The following level is valid.
Value | Meaning
50 | Return the name of the computer, name of the user, open files on the computer, and the name of the transport protocol the client is using. The pbBuffer parameter points to an array of session_info_50 structures.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter.

Windows NT/2000 or later: This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

Windows 95/98/Me: The caller must allocate and deallocate this buffer.

prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a value that receives the total number of entries that could have been enumerated from the current resume position.
resume_handle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing session search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_ClientNameNotFound | A session does not exist with the computer name.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

Remarks

Windows 95/98/Me: See the NetSessionEnum Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetSessionEnum function.

Windows NT/2000 or later: The following code sample demonstrates how to retrieve information about current sessions using a call to the NetSessionEnum function. The sample calls NetSessionEnum, specifying information level 10 (SESSION_INFO_10). The sample loops through the entries and prints the retrieved information. Finally, the code prints the total number of sessions enumerated and frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPSESSION_INFO_10 pBuf = NULL;
   LPSESSION_INFO_10 pTmpBuf;
   DWORD dwLevel = 10;
   DWORD dwPrefMaxLen = -1;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD i;
   DWORD dwTotalCount = 0;
   LPTSTR pszServerName = NULL;
   LPTSTR pszClientName = NULL;
   LPTSTR pszUserName = NULL;
   NET_API_STATUS nStatus;
   //
   // Check command line arguments.
   //
   if (argc > 4)
   {
      wprintf(L"Usage: %s [\\\\ServerName] [\\\\ClientName] [UserName]\n", argv[0]);
      exit(1);
   }

   if (argc >= 2)
      pszServerName = argv[1];

   if (argc >= 3)
      pszClientName = argv[2];

   if (argc == 4)
      pszUserName = argv[3];
   //
   // Call the NetSessionEnum function, specifying level 10.
   //
   do // begin do
   {
      nStatus = NetSessionEnum(pszServerName,
                               pszClientName,
                               pszUserName,
                               dwLevel,
                               (LPBYTE*)&pBuf,
                               dwPrefMaxLen,
                               &dwEntriesRead,
                               &dwTotalEntries,
                               &dwResumeHandle);
      //
      // If the call succeeds,
      //
      if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
      {
         if ((pTmpBuf = pBuf) != NULL)
         {
            //
            // Loop through the entries.
            //
            for (i = 0; (i < dwEntriesRead); i++)
            {
               assert(pTmpBuf != NULL);

               if (pTmpBuf == NULL)
               {
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               // Print the retrieved data.
               //
               wprintf(L"\n\tClient: %s\n", pTmpBuf->sesi10_cname);
               wprintf(L"\tUser:   %s\n", pTmpBuf->sesi10_username);
               printf("\tActive: %d\n", pTmpBuf->sesi10_time);
               printf("\tIdle:   %d\n", pTmpBuf->sesi10_idle_time);

               pTmpBuf++;
               dwTotalCount++;
            }
         }
      }
      //
      // Otherwise, indicate a system error.
      //
      else
         fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      //
      // Free the allocated memory.
      //
      if (pBuf != NULL)
      {
         NetApiBufferFree(pBuf);
         pBuf = NULL;
      }
   }
   //
   // Continue to call NetSessionEnum while
   //  there are more entries.
   //
   while (nStatus == ERROR_MORE_DATA); // end do

   // Check again for an allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of sessions enumerated.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

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. For more information, see IADsSession and IADsFileServiceOperations.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Session Functions, NetSessionGetInfo, SESSION_INFO_0, SESSION_INFO_1, SESSION_INFO_2, SESSION_INFO_10, SESSION_INFO_502, session_info_50


NetSessionGetInfo

The NetSessionGetInfo function retrieves information about a session established between a particular server and workstation.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetSessionGetInfo function at level 1 or level 2. No special group membership is required for level 0 or level 10 calls.

Windows 2000 or later: If you call this function at information level 1 or 2 on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function at information level 1 or 2 on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

Parameter Order

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetSessionGetInfo(
  LPWSTR servername,
  LPWSTR UncClientName,
  LPWSTR username,
  DWORD level,
  LPBYTE *bufptr
);

Windows 95/98/Me: The calling application must use the cbBuffer parameter to specify the size, in bytes, of the information buffer pointed to by the pbBuffer parameter. If the length of the buffer is not large enough to hold all of the data, the function returns as much as will fit in the buffer. The function returns the total number of bytes of information available in the pcbTotalAvail parameter. The Windows NT/Windows 2000 username parameter is not available on this platform. Therefore, the parameter list is as follows.

extern API_FUNCTION
 NetSessionGetInfo(
  const char FAR * pszServer,
  const char FAR * pszClientName,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short  cbBuffer,
  unsigned short FAR * pcbTotalAvail
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
UncClientName
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the computer session for which information is to be returned. This parameter cannot be NULL. For more information, see NetSessionEnum.
username
[in] Pointer to a Unicode string specifying the name of the user whose session information is to be returned. This parameter cannot be NULL.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value Meaning
0 Return the name of the computer that established the session.

Windows NT/2000 or later: The bufptr parameter points to a SESSION_INFO_0 structure.

Windows 95/98/Me: The pbBuffer parameter points to a session_info_0 structure.
1 Return the name of the computer, name of the user, and open files, pipes, and devices on the computer.

Windows NT/2000 or later: The bufptr parameter points to a SESSION_INFO_1 structure.

Windows 95/98/Me: The pbBuffer parameter points to a session_info_1 structure.
2 In addition to the information indicated for level 1, return the type of client and how the user established the session.

Windows NT/2000 or later: The bufptr parameter points to a SESSION_INFO_2 structure.

Windows 95/98/Me: The pbBuffer parameter points to a session_info_2 structure.
10 Return the name of the computer; name of the user; and active and idle times for the session.

Windows NT/2000 or later: The bufptr parameter points to a SESSION_INFO_10 structure.

Windows 95/98/Me: The pbBuffer parameter points to a session_info_10 structure.
50 Return the name of the computer, name of the user, open files on the computer, and the name of the transport protocol the client is using.

Windows 95/98/Me: The pbBuffer parameter points to a session_info_50 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter.

Windows NT/2000 or later: This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Windows 95/98/Me: The caller must allocate and deallocate this buffer.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_ClientNameNotFound | A session does not exist with the computer name.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

Remarks

Windows 95/98/Me: See the NetSessionGetInfo Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetSessionGetInfo function.

Windows NT/2000 or later: The following code sample demonstrates how to retrieve information about a session using a call to the NetSessionGetInfo function. The sample calls NetSessionGetInfo, specifying information level 10 (SESSION_INFO_10). If the call succeeds, the code prints information about the session. Finally, the sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 10;
   LPSESSION_INFO_10 pBuf = NULL;
   LPTSTR pszServerName = NULL;
   LPTSTR pszUNCClientName = NULL;
   LPTSTR pszUserName = NULL;
   NET_API_STATUS nStatus;
   //
   // Check command line arguments.
   //
   if (argc == 3)
   {
      pszUNCClientName = argv[1];
      pszUserName = argv[2];
   }
   else if (argc == 4)
   {
      pszServerName = argv[1];
      pszUNCClientName = argv[2];
      pszUserName = argv[3];
   }
   else
   {
      wprintf(L"Usage: %s [\\\\ServerName] \\\\ClientName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetSessionGetInfo function, specifying level 10.
   //
   nStatus = NetSessionGetInfo(pszServerName,
                               pszUNCClientName,
                               pszUserName,
                               dwLevel,
                               (LPBYTE *)&pBuf);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      if (pBuf != NULL)
      {
         //
         // Print the session information.
         //
         wprintf(L"\n\tClient: %s\n", pBuf->sesi10_cname);
         wprintf(L"\tUser:   %s\n", pBuf->sesi10_username);
         printf("\tActive: %d\n", pBuf->sesi10_time);
         printf("\tIdle:   %d\n", pBuf->sesi10_idle_time);
      }
   }
   //
   // Otherwise, indicate a system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

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. For more information, see IADsSession and IADsFileServiceOperations.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Session Functions, NetSessionDel, NetSessionEnum, SESSION_INFO_0, SESSION_INFO_1, SESSION_INFO_2, SESSION_INFO_10, session_info_0, session_info_1, session_info_2, session_info_10, session_info_50


NetShareAdd

The NetShareAdd function shares a server resource.

Security Requirements

Only members of the Administrators or Account Operators local group or those with Communication, Print, or Server operator group membership can successfully execute the NetShareAdd function. The Print operator can add only Printer queues. The Communication operator can add only communication-device queues.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetShareAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Windows 95/98/Me: You must specify the size of the information buffer, in bytes, using the cbBuffer parameter. The Windows NT/Windows 2000 parm_err parameter is not available on this platform. Therefore, the parameter list is as follows.

extern API_FUNCTION
 NetShareAdd(
  const char FAR * pszServer,
  short sLevel,
  const char FAR * pbBuffer,
  unsigned short  cbBuffer
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.

Windows NT/2000 or later: The following levels are valid.
Value | Meaning
2 | Specifies information about the shared resource, including name of the resource, type and permissions, and number of connections. The buf parameter points to a SHARE_INFO_2 structure.
502 | Specifies information about the shared resource, including name of the resource, type and permissions, number of connections, and other pertinent information. The buf parameter points to a SHARE_INFO_502 structure.

Windows 95/98/Me: The following level is valid.
Value | Meaning
50 | Specifies information about the shared resource, including the name and type of the resource, a comment associated with the resource, and passwords. The pbBuffer parameter points to a share_info_50 structure. Note that the string you specify in the shi50_path member must contain only uppercase characters. If the path contains lowercase characters, calls to NetShareAdd can fail with NERR_UnknownDevDir or ERROR_BAD_NET_NAME.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the share information structure that causes the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error. For more information, see the NetShareSetInfo function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_NAME | The character or file system name is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
NERR_DuplicateShare | The share name is already in use on this server.
NERR_RedirectedPath | The operation is invalid for a redirected resource. The specified device name is assigned to a shared resource.
NERR_UnknownDevDir | The device or directory does not exist.

Remarks

Windows 95/98/Me: See the NetShareAdd Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetShareAdd function.

Windows NT/2000 or later: The following code sample demonstrates how to share a network resource using a call to the NetShareAdd function. The code sample fills in the members of the SHARE_INFO_2 structure and calls NetShareAdd, specifying information level 2.

#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>

void wmain( int argc, TCHAR *argv[ ])
{
   NET_API_STATUS res;
   SHARE_INFO_2 p;
   DWORD parm_err = 0;

   if(argc<2)
      printf("Usage: NetShareAdd server\n");
   else
   {
      //
      // Fill in the SHARE_INFO_2 structure.
      //
      p.shi2_netname = TEXT("TESTSHARE");
      p.shi2_type = STYPE_DISKTREE; // disk drive
      p.shi2_remark = TEXT("TESTSHARE to test NetShareAdd");
      p.shi2_permissions = 0;
      p.shi2_max_uses = 4;
      p.shi2_current_uses = 0;
      p.shi2_path = TEXT("C:\\");
      p.shi2_passwd = NULL; // no password
      //
      // Call the NetShareAdd function,
      //  specifying level 2.
      //
      res=NetShareAdd(argv[1], 2, (LPBYTE) &p, &parm_err);
      //
      // If the call succeeds, inform the user.
      //
      if(res==0)
         printf("Share created.\n");

      // Otherwise, print an error,
      //  and identify the parameter in error.
      //
      else
         printf("Error: %u\tparmerr=%u\n", res, parm_err);
   }
   return;
}

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. For more information, see IADsFileShare.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Share Functions, NetShareDel, NetShareSetInfo, SHARE_INFO_2, SHARE_INFO_502, share_info_50


NetShareCheck

The NetShareCheck function checks whether or not a server is sharing a device.

Security Requirements

No special group membership is required to successfully execute the NetShareCheck function.

NET_API_STATUS NetShareCheck(
  LPWSTR servername,
  LPWSTR device,
  LPDWORD type
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
device
[in] Pointer to a Unicode string specifying the name of the device to check for shared access.
type
[out] Pointer to an address that receives the type of the shared device. This parameter is set only if the function returns successfully. This parameter can be one of the following values.
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)
STYPE_SPECIAL | Special share reserved for interprocess communication (IPC$) or remote administration of the server (ADMIN$). Can also refer to administrative shares such as C$, D$, E$, and so forth. For more information, see the network management share functions.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_DeviceNotShared | The device is not shared.

Remarks

The following code sample demonstrates how to check whether a server is sharing a device, using a call to the NetShareCheck function. The function returns the type of device being shared, as described in the preceding documentation for the type parameter.

#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>

void wmain( int argc, TCHAR *argv[ ])
{
   NET_API_STATUS res;
   DWORD devType = 0;

   if(argc<3)
      printf("Usage: NetShareCheck server device\n");
   else
   {
      //
      // Call the NetShareCheck function.
      //
      res=NetShareCheck(argv[1], _wcsupr(argv[2]), &devType);
      //
      // If the function succeeds, inform the user.
      //
      if(res==0)
         printf("Device is shared as type %u.\n",devType);
      //
      // Otherwise, print the error.
      //
      else
         printf("Error: %u\n", res);
   }
   return;
}

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. For more information, see IADsFileShare.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Share Functions, NetShareEnum, NetShareGetInfo


NetShareDel

The NetShareDel function deletes a share name from a server's list of shared resources, disconnecting all connections to the shared resource.

Security Requirements

Only members of the Administrators or Account Operators local group or those with Communication, Print, or Server operator group membership can successfully execute the NetShareDel function. The Print operator can delete only Printer queues. The Communication operator can delete only communication-device queues.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetShareDel(
  LPWSTR servername,
  LPWSTR netname,
  DWORD reserved
);

Windows 95/98/Me: Following is the function prototype on Windows 95/98.

extern API_FUNCTION
 NetShareDel(
  const char FAR * pszServer,
  const char FAR * pszNetName,
  unsigned short  usReserved
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
netname
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the share to delete.
reserved
Reserved, must be zero.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_NetNameNotFound | The share name does not exist.

Remarks

Windows 95/98/Me: See the NetShareDel Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetShareDel function.

Windows NT/2000 or later: The following code sample demonstrates how to delete a share using a call to the NetShareDel function.

#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>

void wmain( int argc, TCHAR *argv[ ])
{
   NET_API_STATUS res;

   if(argc<3)
      printf("Usage: NetShareDel server share\n");
   else
   {
      //
      // Call the NetShareDel function to delete the share.
      //
      res=NetShareDel(argv[1], argv[2], 0);
      //
      // Display the result of the call.
      //
      if(res==0)
         printf("Share Removed.\n");
      else
         printf("Error: %u\n", res);
   }
   return;
}

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. For more information, see IADsFileShare.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Share Functions, NetShareAdd


NetShareEnum

The NetShareEnum function retrieves information about each shared resource on a server.

Win32-based applications can also use the WNetEnumResource function. However, WNetEnumResource does not enumerate hidden shares or users connected to a share.

Security Requirements

Windows NT: Administrator or Communication, Print, or Server operator group membership is required to successfully execute the NetShareEnum function at levels 2 and 502. No special group membership is required for level 0 or level 1 calls.

Windows 2000 or later: If you call this function at information level 2 or 502 on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function at information level 2 or 502 on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

Parameter Order

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetShareEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Windows 95/98/Me: The calling application must use the cbBuffer parameter to specify the size, in bytes, of the information buffer pointed to by the pbBuffer parameter. (The cbBuffer parameter replaces the Windows NT/Windows 2000 prefmaxlen parameter.) A resume handle parameter is not available on this platform. Therefore, the parameter list is as follows.

extern API_FUNCTION
 NetShareEnum(
  const char FAR * pszServer,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short  cbBuffer,
  unsigned short FAR * pcEntriesRead,
  unsigned short FAR * pcTotalAvail
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Windows NT/2000 or later: Return share names. The bufptr parameter points to an array of SHARE_INFO_0 structures.
1 Return information about shared resources, including the name and type of the resource, and a comment associated with the resource.

Windows NT/2000 or later: The bufptr parameter points to an array of SHARE_INFO_1 structures.

Windows 95/98/Me: The pbBuffer parameter points to an array of share_info_1 structures.

2 | Windows NT/2000 or later: Return information about shared resources, including name of the resource, type and permissions, password, and number of connections. The bufptr parameter points to an array of SHARE_INFO_2 structures.
50 | Windows 95/98/Me: Return information about shared resources, including the name and type of the resource, a comment associated with the resource, and passwords. The pbBuffer parameter points to an array of share_info_50 structures.
502 | Windows NT/2000 or later: Return information about shared resources, including name of the resource, type and permissions, number of connections, and other pertinent information. The bufptr parameter points to an array of SHARE_INFO_502 structures.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter.

Windows NT/2000 or later: This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

Windows 95/98/Me: The caller must allocate and deallocate this buffer.

prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a value that receives the total number of entries that could have been enumerated.
resume_handle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing share search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

To retrieve a value that indicates whether a share is the root volume in a Dfs tree structure, you must call the NetShareGetInfo function and specify information level 1005.

Windows 95/98/Me: See the NetShareEnum Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetShareEnum function.

Windows NT/2000 or later: The following code sample demonstrates how to retrieve information about each shared resource on a server using a call to the NetShareEnum function. The sample calls NetShareEnum, specifying information level 502 (SHARE_INFO_502). If the call succeeds, the code loops through the entries and prints information about each share. The sample also calls the IsValidSecurityDescriptor function to validate the shi502_security_descriptor member. Finally, the code sample frees the memory allocated for the information buffer.

#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>

void wmain( int argc, TCHAR *lpszArgv[ ])
{
   PSHARE_INFO_502 BufPtr,p;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL;
   DWORD er=0,tr=0,resume=0, i;

   switch(argc)
   {
   case 2:
      lpszServer = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareEnum <servername>\n");
      return;
   }
   //
   // Print a report header.
   //
   printf("Share:              Local Path:                   Uses:   Descriptor:\n");
   printf("---------------------------------------------------------------------\n");
   //
   // Call the NetShareEnum function; specify level 502.
   //
   do // begin do
   {
      res = NetShareEnum (lpszServer, 502, (LPBYTE *) &BufPtr, -1, &er, &tr, &resume);
      //
      // If the call succeeds,
      //
      if(res == ERROR_SUCCESS || res == ERROR_MORE_DATA)
      {
         p=BufPtr;
         //
         // Loop through the entries;
         //  print retrieved data.
         //
         for(i=1;i<=er;i++)
         {
            printf("%-20S%-30S%-8u",p->shi502_netname, p->shi502_path, p->shi502_current_uses);
            //
            // Validate the value of the
            //  shi502_security_descriptor member.
            //
            if (IsValidSecurityDescriptor(p->shi502_security_descriptor))
               printf("Yes\n");
            else
               printf("No\n");
            p++;
         }
         //
         // Free the allocated buffer.
         //
         NetApiBufferFree(BufPtr);
      }
      else
         printf("Error: %ld\n",res);
   }
   // Continue to call NetShareEnum while
   //  there are more entries.
   //
   while (res==ERROR_MORE_DATA); // end do
   return;
}

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. For more information, see IADsFileShare.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Share Functions, SHARE_INFO_0, SHARE_INFO_1, SHARE_INFO_2, SHARE_INFO_502, share_info_1, share_info_50


NetShareGetInfo

The NetShareGetInfo function retrieves information about a particular shared resource on a server.

Security Requirements

Only members of the Administrators or Account Operators local group or those with Communication, Print, or Server operator group membership can successfully execute the NetShareGetInfo function at level 2. No special group membership is required for level 0 or level 1 calls.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetShareGetInfo(
  LPWSTR servername,
  LPWSTR netname,
  DWORD level,
  LPBYTE *bufptr
);

Windows 95/98/Me: The calling application must use the cbBuffer parameter to specify the size, in bytes, of the information buffer pointed to by the pbBuffer parameter. If the length of the buffer is not large enough to hold all of the data, the function returns as much as will fit in the buffer. The function returns the total number of bytes of information available in the pcbTotalAvail parameter. The parameter list is as follows.

extern API_FUNCTION
 NetShareGetInfo(
  const char FAR * pszServer,
  const char FAR * pszNetName,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short  cbBuffer,
  unsigned short FAR * pcbTotalAvail
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
netname
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the share for which to return information.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Windows NT/2000 or later: Return the share name. The bufptr parameter points to a SHARE_INFO_0 structure.
1 | Windows NT/2000 or later: Return information about the shared resource, including the name and type of the resource, and a comment associated with the resource. The bufptr parameter points to a SHARE_INFO_1 structure.
2 | Windows NT/2000 or later: Return information about the shared resource, including name of the resource, type and permissions, password, and number of connections. The bufptr parameter points to a SHARE_INFO_2 structure.
50 | Windows 95/98/Me: Return information about the shared resource, including the name and type of the resource, a comment associated with the resource, and passwords. The pbBuffer parameter points to a share_info_50 structure.
501 | Windows NT/2000 or later: Return the name and type of the resource, and a comment associated with the resource. The bufptr parameter points to a SHARE_INFO_501 structure.
502 | Windows NT/2000 or later: Return information about the shared resource, including name of the resource, type and permissions, number of connections, and other pertinent information. The bufptr parameter points to a SHARE_INFO_502 structure.
1005 | Windows NT/2000 or later: Return a value that indicates whether the share is the root volume in a Dfs tree structure. The bufptr parameter points to a SHARE_INFO_1005 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter.

Windows NT/2000 or later: This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.

Windows 95/98/Me: The caller must allocate and deallocate this buffer.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory is available.
NERR_BufTooSmall | The supplied buffer is too small.
NERR_NetNameNotFound | The share name does not exist.

Remarks

Windows 95/98/Me: See the NetShareGetInfo Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetShareGetInfo function.

Windows NT/2000 or later: The following code sample demonstrates how to retrieve information about a particular shared resource using a call to the NetShareGetInfo function. The sample calls NetShareGetInfo, specifying information level 502 (SHARE_INFO_502). If the call succeeds, the code prints the retrieved data. The sample also calls the IsValidSecurityDescriptor function to validate the shi502_security_descriptor member. Finally, the sample frees the memory allocated for the information buffer.

#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>

void wmain( int argc, TCHAR *lpszArgv[ ])
{
   PSHARE_INFO_502 BufPtr;
   NET_API_STATUS res;
   LPTSTR   lpszServer = NULL, lpszShare;
   //
   // Check command line arguments.
   //
   switch(argc)
   {
   case 3:
      lpszServer = lpszArgv[2];
   case 2:
      lpszShare = lpszArgv[1];
      break;
   default:
      printf("Usage: NetShareGetInfo sharename <servername>\n");
      return;
   }
   //
   // Call the NetShareGetInfo function, specifying level 502.
   //
   if((res = NetShareGetInfo (lpszServer,lpszShare,502,(LPBYTE *) &BufPtr)) == ERROR_SUCCESS)
   {
      //
      // Print the retrieved data.
      //
      printf("%S\t%S\t%u\n",BufPtr->shi502_netname, BufPtr->shi502_path, BufPtr->shi502_current_uses);
      //
      // Validate the value of the
      //  shi502_security_descriptor member.
      //
      if (IsValidSecurityDescriptor(BufPtr->shi502_security_descriptor))
         printf("It has a valid Security Descriptor.\n");
      else
         printf("It does not have a valid Security Descriptor.\n");
      //
      // Free the allocated memory.
      //
      NetApiBufferFree(BufPtr);
   }
   else
      printf("Error: %ld\n",res);
   return;
}

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. For more information, see IADsFileShare.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Share Functions, SHARE_INFO_0, SHARE_INFO_1, SHARE_INFO_2, SHARE_INFO_501, SHARE_INFO_502, SHARE_INFO_1005, share_info_50


NetShareSetInfo

The NetShareSetInfo function sets the parameters of a shared resource.

Security Requirements

Only the Administrators local group or Communication, Print, or Server operator group membership is required to successfully execute the NetShareSetInfo function. The Print operator can set information only about Printer queues. The Communication operator can set information only about communication-device queues.

Windows NT/2000 or later: The parameter order is as follows.

NET_API_STATUS NetShareSetInfo(
  LPWSTR servername,
  LPWSTR netname,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Windows 95/98/Me: You must specify the size of the information buffer, in bytes, using the cbBuffer parameter. The parameter list is as follows.

extern API_FUNCTION
 NetShareSetInfo(
  const char FAR * pszServer,
  const char FAR * pszNetName,
  short sLevel,
  char FAR * pbBuffer,
  unsigned short cbBuffer,
  short sParmNum
);

Parameters

servername
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
netname
[in] Pointer to a Unicode (Windows NT/2000) or ANSI (Windows 95/98) string specifying the name of the share to set information on.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.

Windows NT/2000 or later: The following levels are valid.
Value | Meaning
1 | Specifies information about the shared resource, including the name and type of the resource, and a comment associated with the resource. The buf parameter points to a SHARE_INFO_1 structure.
2 | Specifies information about the shared resource, including name of the resource, type and permissions, password, and number of connections. The buf parameter points to a SHARE_INFO_2 structure.
502 | Specifies information about the shared resource, including name of the resource, type and permissions, number of connections, and other pertinent information. The buf parameter points to a SHARE_INFO_502 structure.
1004 | Specifies a comment associated with the shared resource. The buf parameter points to a SHARE_INFO_1004 structure.
1006 | Specifies the maximum number of concurrent connections that the shared resource can accommodate. The buf parameter points to a SHARE_INFO_1006 structure.
1501 | Windows 2000 or later: Specifies the security descriptor associated with the specified share. The buf parameter points to a SHARE_INFO_1501 structure.

Windows 95/98/Me: The following level is valid.
Value | Meaning
50 | Specifies information about the shared resource, including the name and type of the resource, a comment associated with the resource, and passwords. The pbBuffer parameter points to a share_info_50 structure. Note that the string you specify in the shi50_path member must contain only uppercase characters. If the path contains lowercase characters, calls to NetShareSetInfo can fail with NERR_UnknownDevDir or ERROR_BAD_NET_NAME.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the share information structure that causes the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The value specified for the level parameter is invalid.
ERROR_INVALID_PARAMETER | The specified parameter is invalid. For more information, see the following Remarks section.
NERR_NetNameNotFound | The share name does not exist.

Remarks

If the NetShareSetInfo function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the share information structure that is invalid. (A share information structure begins with SHARE_INFO_ and its format is specified by the level parameter.) The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error. (The prefix shi*_ indicates that the member can begin with multiple prefixes, for example, shi2_ or shi502_.)

Value | Member
SHARE_NETNAME_PARMNUM | shi*_netname
SHARE_TYPE_PARMNUM | shi*_type
SHARE_REMARK_PARMNUM | shi*_remark
SHARE_PERMISSIONS_PARMNUM | shi*_permissions
SHARE_MAX_USES_PARMNUM | shi*_max_uses
SHARE_CURRENT_USES_PARMNUM | shi*_current_uses
SHARE_PATH_PARMNUM | shi*_path
SHARE_PASSWD_PARMNUM | shi*_passwd
SHARE_FILE_SD_PARMNUM | shi*_security_descriptor

Windows 95/98/Me: See the NetShareSetInfo Sample (Windows 95/98) topic to view a code sample that demonstrates how to use the NetShareSetInfo function.

Windows NT/2000 or later: The following code sample demonstrates how to set the comment associated with a shared resource using a call to the NetShareSetInfo function. To do this, the sample specifies information level 1004 (SHARE_INFO_1004).

#define UNICODE
#include <windows.h>
#include <stdio.h>
#include <lm.h>

void wmain( int argc, TCHAR *argv[ ])
{
   SHARE_INFO_1004 p;
   NET_API_STATUS res;
   DWORD parm_err = 0;

   if(argc<4)
      printf("Usage: SetInfo server share \"remark\"\n");
   else
   {
      //
      // Fill in SHARE_INFO_1004 structure member.
      //
      p.shi1004_remark=argv[3];
      //
      // Call the NetShareSetInfo function,
      //  specifying information level 1004.
      //
      res=NetShareSetInfo(argv[1], argv[2], 1004, (LPBYTE)&p, &parm_err);
      //
      // Display the result of the call.
      //
      if(res==0)
         printf("Remark set.\n");
      else
         printf("Error: %u\tparmerr=%u\n", res, parm_err);
   }
   return;
}

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. For more information, see IADsFileShare.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h (Windows NT/2000) or Svrapi.h (Windows 95/98); include Lm.h (Windows NT/2000).
Library: Use Netapi32.lib (Windows NT/2000) or Svrapi.lib (Windows 95/98).

See Also

Network Management Overview, Network Management Functions, Share Functions, NetShareGetInfo, SHARE_INFO_1, SHARE_INFO_2, SHARE_INFO_502, SHARE_INFO_1004, SHARE_INFO_1006, SHARE_INFO_1501, share_info_50


NetStatisticsGet

The NetStatisticsGet function retrieves operating statistics for a service. Currently, only the workstation and server services are supported.

Security Requirements

Only members of the Administrators or Account Operators local group can successfully execute the NetStatisticsGet function on a remote server.

NET_API_STATUS NetStatisticsGet(
  LPWSTR server,
  LPWSTR service,
  DWORD level,
  DWORD options,
  LPBYTE *bufptr
);

Parameters

server
[in] Pointer to a Unicode string that specifies the name of the server on which to execute NetStatisticsGet. The string must begin with \\. If this parameter is NULL, the local computer is used.
service
[in] Pointer to a Unicode string that specifies the name of the service about which to get the statistics. Only the values SERVICE_SERVER and SERVICE_WORKSTATION are currently allowed.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Return statistics about a workstation or a server. The bufptr parameter points to a STAT_WORKSTATION_0 or a STAT_SERVER_0 structure.

options
[in] This parameter must be zero.
bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmstats.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Statistics Functions, NetServerGetInfo, STAT_SERVER_0, STAT_WORKSTATION_0


NetUnjoinDomain

The NetUnjoinDomain function unjoins a computer from a workgroup or a domain.

Security Requirements

Unjoining (and joining) a computer to a domain or workgroup can be performed only by a member of the Administrators local group on the target computer. If you call the NetUnjoinDomain function remotely, you must supply credentials because you cannot delegate credentials under these circumstances.

NET_API_STATUS NetUnjoinDomain(
  LPCWSTR lpServer,
  LPCWSTR lpAccount,
  LPCWSTR lpPassword,
  DWORD   fUnjoinOptions
);

Parameters

lpServer
[in] Pointer to a constant null-terminated Unicode character string that specifies the name of the computer on which to call the function. If this parameter is NULL, the local computer is used.
lpAccount
[in] Pointer to a constant null-terminated Unicode character string that specifies the account name to use when connecting to the domain controller. The string must specify either a domain NetBIOS name and user account (for example, "REDMOND\user") or the user principal name (UPN) of the user in the form of an Internet-style login name (for example, "someone@microsoft.com"). If this parameter is NULL, the caller's context is used.
lpPassword
[in] If the lpAccount parameter specifies an account name, this parameter must point to the password to use when connecting to the domain controller. Otherwise, this parameter must be NULL.
fUnjoinOptions
[in] Specifies the unjoin options. If this parameter is NETSETUP_ACCT_DELETE, the account is disabled when the unjoin occurs. Note that this option does not delete the account. Currently, there are no other unjoin options defined.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes or one of the Win32 error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter is incorrect.
NERR_SetupNotJoined | The computer is not currently joined to a domain.
NERR_SetupDomainController | This computer is a domain controller and cannot be unjoined from a domain.

Remarks

Different processes, or different threads of the same process, should not call the NetUnjoinDomain function at the same time. This situation can leave the computer in an inconsistent state.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmjoin.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, NetJoinDomain, NetRenameMachineInDomain


NetUseAdd

The NetUseAdd function establishes a connection between the local computer and a remote server. You can specify a local drive letter or a printer device to connect. If you do not specify a local drive letter or printer device, the function authenticates the client with the server for future connections.

Win32-based applications can also use the WNetAddConnection2 and WNetAddConnection3 functions to redirect a local device to a network resource.

Security Requirements

No special group membership is required to call the NetUseAdd function. This function cannot be executed on a remote server.

NET_API_STATUS NetUseAdd (
  LPWSTR UncServerName,
  DWORD Level,
  LPBYTE Buf,
  LPDWORD ParmError
);

Parameters

UncServerName
[in] Reserved; must be NULL.
Level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
1 | Specifies information about the connection between a local device and a shared resource, including connection status and type. The Buf parameter is a pointer to a USE_INFO_1 structure.
2 | Specifies information about the connection between a local device and a shared resource. Information includes the connection status and type, and a user name and domain name. The Buf parameter is a pointer to a USE_INFO_2 structure.

Buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the Level parameter.
ParmError
[out] Pointer to a DWORD value that receives the index of the first member of the information structure in error when the ERROR_INVALID_PARAMETER error is returned. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

If the NetUseAdd function returns ERROR_INVALID_PARAMETER, you can use the ParmError parameter to indicate the first member of the information structure that is invalid. (The information structure begins with USE_INFO_ and its format is specified by the Level parameter.) The following table lists the values that can be returned in the ParmError parameter and the corresponding structure member that is in error. (The prefix ui*_ indicates that the member can begin with multiple prefixes, for example, ui1_ or ui2_.)

Value | Member
USE_LOCAL_PARMNUM | ui*_local
USE_REMOTE_PARMNUM | ui*_remote
USE_PASSWORD_PARMNUM | ui*_password
USE_ASGTYPE_PARMNUM | ui*_asg_type
USE_USERNAME_PARMNUM | ui*_username
USE_DOMAINNAME_PARMNUM | ui*_domainname

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmuse.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Use Functions, USE_INFO_1, USE_INFO_2, NetUseDel, WNetAddConnection2, WNetAddConnection3


NetUseDel

The NetUseDel function ends a connection to a shared resource.

Win32-based applications can also use the WNetCancelConnection2 function to terminate a network connection.

Security Requirements

No special group membership is required to call the NetUseDel function. This function cannot be executed on a remote server.

NET_API_STATUS NetUseDel (
  LPWSTR UncServerName,
  LPWSTR UseName,
  DWORD ForceCond
);

Parameters

UncServerName
[in] Reserved; must be NULL.
UseName
[in] Pointer to a Unicode string specifying the path of the connection to delete.
ForceCond
[in] Specifies the level of force to use in deleting the connection. This parameter can be one of the following values.
Value | Meaning
USE_NOFORCE | Fail the disconnection if open files exist on the connection.
USE_FORCE | Fail the disconnection if open files exist on the connection.
USE_LOTS_OF_FORCE | Close any open files and delete the connection.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmuse.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Use Functions, NetUseAdd, WNetCancelConnection2


NetUseEnum

The NetUseEnum function lists all current connections between the local computer and resources on remote servers.

Win32-based applications can also use the WNetOpenEnum and the WNetEnumResource functions to enumerate network resources or connections.

Security Requirements

No special group membership is required to call the NetUseEnum function. This function cannot be executed on a remote server.

NET_API_STATUS NetUseEnum (
  LPWSTR UncServerName,
  DWORD Level,
  LPBYTE *BufPtr,
  DWORD PreferedMaximumSize,
  LPDWORD EntriesRead,
  LPDWORD TotalEntries,
  LPDWORD ResumeHandle
);

Parameters

UncServerName
[in] Reserved; must be NULL.
Level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies a local device name and the share name of a remote resource. The BufPtr parameter points to an array of USE_INFO_0 structures.
1 | Specifies information about the connection between a local device and a shared resource, including connection status and type. The BufPtr parameter points to an array of USE_INFO_1 structures.
2 | Specifies information about the connection between a local device and a shared resource. Information includes the connection status, connection type, user name, and domain name. The BufPtr parameter points to an array of USE_INFO_2 structures.

BufPtr
[out] Pointer to the buffer that receives the information structures. The format of this data depends on the value of the Level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
PreferedMaximumSize
[in] Specifies the preferred maximum length of the data returned, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
EntriesRead
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
TotalEntries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
ResumeHandle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue the search. The handle should be zero on the first call and left unchanged for subsequent calls. If ResumeHandle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

To retrieve information about one network connection, you can call the NetUseGetInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmuse.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Use Functions, USE_INFO_0, USE_INFO_1, USE_INFO_2, NetUseGetInfo, WNetEnumResource, WNetOpenEnum


NetUseGetInfo

The NetUseGetInfo function retrieves information about a connection to a shared resource.

Win32-based applications can also use the WNetGetConnection function to retrieve the name of a network resource associated with a local device.

Security Requirements

No special group membership is required to call the NetUseGetInfo function. This function cannot be executed on a remote server.

NET_API_STATUS NetUseGetInfo (
  LPWSTR UncServerName,
  LPWSTR UseName,
  DWORD Level,
  LPBYTE *BufPtr
);

Parameters

UncServerName
[in] Reserved; must be NULL.
UseName
[in] Pointer to a Unicode string specifying the name of the connection for which to return information.
Level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies a local device name and the share name of a remote resource. The BufPtr parameter is a pointer to a USE_INFO_0 structure.
1 | Specifies information about the connection between a local device and a shared resource, including connection status and type. The BufPtr parameter is a pointer to a USE_INFO_1 structure.
2 | Specifies information about the connection between a local device and a shared resource. Information includes the connection status, connection type, user name, and domain name. The BufPtr parameter is a pointer to a USE_INFO_2 structure.

BufPtr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the Level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value is a Win32 API error code. For a list of error codes, see Error Codes.

Remarks

To list all current connections between the local computer and resources on remote servers, you can call the NetUseEnum function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmuse.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Use Functions, USE_INFO_0, USE_INFO_1, USE_INFO_2, WNetGetConnection, NetUseEnum


NetUserAdd

The NetUserAdd function adds a user account and assigns a password and privilege level.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetUserAdd function. Only members of the Administrators local group can add an Administrators privilege account.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserAdd(
  LPCWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
1 | Specifies information about the user account. The buf parameter points to a USER_INFO_1 structure.
2 | Specifies level one information and additional attributes about the user account. The buf parameter points to a USER_INFO_2 structure.
3 | Specifies level two information and additional attributes about the user account. This level is valid only on Windows NT/Windows 2000 servers. The buf parameter points to a USER_INFO_3 structure. Note that on Whistler and later, it is recommended that you use USER_INFO_4 instead.
4 | Whistler: Specifies level two information and additional attributes about the user account. This level is valid only on Windows NT/Windows 2000 servers. The buf parameter points to a USER_INFO_4 structure.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the user information structure that causes ERROR_INVALID_PARAMETER. If this parameter is NULL, the index is not returned on error. For more information, see the NetUserSetInfo function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupExists | The group already exists.
NERR_UserExists | The user account already exists.
NERR_PasswordTooShort | The password is shorter than required. (The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.)

Remarks

Server users must use a system in which the server creates a WINDOWS NT system account for the new user. The creation of this account is controlled by several parameters in the server's LANMAN.INI file.

If the newly added user already exists as a system user, the usri1_home_dir member of the USER_INFO_1 structure is ignored.

When you call the NetUserAdd function and specify information level 1, the call initializes the additional members in the USER_INFO_2, USER_INFO_3, and USER_INFO_4 structures to their default values. You can change the default values by making subsequent calls to the NetUserSetInfo function. The default values supplied are listed following. (The prefix usriX indicates that the member can begin with multiple prefixes, for example, usri2_ or usri4_.)

Member | Default Value
usriX_auth_flags | None (0)
usriX_full_name | usri1_name
usriX_usr_comment | None (null string)
usriX_parms | None (null string)
usriX_workstations | All (null string)
usriX_acct_expires | Never (TIMEQ_FOREVER)
usriX_max_storage | Unlimited (USER_MAXSTORAGE_UNLIMITED)
usriX_logon_hours | Logon allowed at any time (each element 0xFF; all bits set to 1)
usriX_logon_server | Any domain controller (\\*)
usriX_country_code | Current country_code on the server
usriX_code_page | 0

The following code sample demonstrates how to add a user account and assign a privilege level using a call to the NetUserAdd function. The code sample fills in the members of the USER_INFO_1 structure and calls NetUserAdd, specifying information level 1.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   USER_INFO_1 ui;
   DWORD dwLevel = 1;
   DWORD dwError = 0;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Set up the USER_INFO_1 structure.
   //  USER_PRIV_USER: name identifies a user,
   //    rather than an administrator or a guest.
   //  UF_SCRIPT: required for LAN Manager 2.0 and
   //    Windows NT/Windows 2000.
   //
   ui.usri1_name = argv[2];
   ui.usri1_password = argv[2];
   ui.usri1_priv = USER_PRIV_USER;
   ui.usri1_home_dir = NULL;
   ui.usri1_comment = NULL;
   ui.usri1_flags = UF_SCRIPT;
   ui.usri1_script_path = NULL;
   //
   // Call the NetUserAdd function, specifying level 1.
   //
   nStatus = NetUserAdd(argv[1],
                        dwLevel,
                        (LPBYTE)&ui,
                        &dwError);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User %s has been successfully added on %s\n",
               argv[2], argv[1]);
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

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. For more information, see IADsUser and IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, NetUserEnum, NetUserSetInfo, NetUserDel, USER_INFO_1, USER_INFO_2, USER_INFO_4


NetUserChangePassword

The NetUserChangePassword function changes a user's password for a specified network server or domain.

Security Requirements

Windows NT: A server or domain can be configured to require a user to log on before changing the password on a user account. In that case, only members of the Administrators or Account Operators local group or the user can change the password for a user account. If logon is not required, a user can change the password for any user account, as long as the user knows the current password.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserChangePassword(
  LPCWSTR domainname,
  LPCWSTR username,
  LPCWSTR oldpassword,
  LPCWSTR newpassword
);

Parameters

domainname
[in] Pointer to a constant null-terminated Unicode string that specifies the name of a remote server or domain. The NetUserChangePassword function changes the user's password on the specified remote server or domain.

If this parameter is NULL, the logon domain of the caller is used.

username
[in] Pointer to a constant null-terminated Unicode string that specifies a user name. The NetUserChangePassword function changes the password for the specified user.

If this parameter is NULL, the logon name of the caller is used.

oldpassword
[in] Pointer to a constant null-terminated Unicode string that specifies the user's old password.
newpassword
[in] Pointer to a constant null-terminated Unicode string that specifies the user's new password.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PASSWORD | The user has entered an invalid password.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_UserNotFound | The user name could not be found.
NERR_PasswordTooShort | The password is shorter than required. (The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.)

Remarks

In some cases, the process that calls the NetUserChangePassword function must also have the SE_CHANGE_NOTIFY_NAME privilege enabled; otherwise, NetUserChangePassword fails and GetLastError returns ERROR_ACCESS_DENIED. This privilege is not required for the local system account or for accounts that are members of the administrators group. By default, SE_CHANGE_NOTIFY_NAME is enabled for all users, but some administrators may disable the privilege for everyone. For more information about account privileges, see Privileges.

The following code sample demonstrates how to change a user's password with a call to the NetUserChangePassword function. All parameters to the function are required.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwError = 0;
   NET_API_STATUS nStatus;
   //
   // All parameters are required.
   //
   if (argc != 5)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName OldPassword NewPassword\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserChangePassword function.
   //
   nStatus = NetUserChangePassword(argv[1], argv[2], argv[3], argv[4]);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User password has been changed successfully\n");
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

See Forcing a User to Change the Logon Password for a code sample that demonstrates how to force a user to change the logon password on the next logon using the NetUserGetInfo and NetUserSetInfo functions.

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. For more information, see IADsUser and IADsComputer.

Windows 95/98/Me: You can use the PwdChangePassword function to change a user's Windows logon password on Windows 95 and Windows 98. The PwdChangePassword function is defined in the header file Pwdspi.h, which is distributed with the Windows 95 Driver Development Kit (DDK). For more information about PwdChangePassword, see the Windows 95 DDK documentation. For more information about designing a routine to change domain passwords on Windows 95 and Windows 98, as well as a code sample, see the following article in the Microsoft Knowledge Base:

ARTICLE ID: Q177200
TITLE: HOWTO: Programmatically Change Network Password Under Windows 95.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, NetUserSetInfo, NetUserGetInfo


NetUserDel

The NetUserDel function deletes a user account from a server.

Security Requirements

Windows NT: Only members of the Administrators or the Account Operators local group can successfully execute NetUserDel on a remote server or on a computer that has local security enabled. Only members of the Administrators local group can delete an Administrators privilege account.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserDel(
  LPCWSTR servername,
  LPCWSTR username
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
username
[in] Pointer to a constant Unicode string specifying the name of the user account to delete.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_UserNotFound | The user name could not be found.

Remarks

An account cannot be deleted while a user or application is accessing a server resource. If the user was added to the system with a call to the NetUserAdd function, deleting the user also deletes the user's system account.

The following code sample demonstrates how to delete a user account with a call to the NetUserDel function.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwError = 0;
   NET_API_STATUS nStatus;
   //
   // All parameters are required.
   //
   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserDel function to delete the share.
   //
   nStatus = NetUserDel(argv[1], argv[2]);
   //
   // Display the result of the call.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User %s has been successfully deleted on %s\n",
               argv[2], argv[1]);
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

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. For more information, see IADsUser and IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, NetUserAdd, NetUserEnum, NetUserSetInfo


NetUserEnum

The NetUserEnum function provides information about all user accounts on a server.

To quickly enumerate user, computer, or global group account information, call the NetQueryDisplayInformation function.

Security Requirements

Windows NT: No special group membership is required to successfully execute the NetUserEnum function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserEnum(
  LPCWSTR servername,
  DWORD level,
  DWORD filter,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resume_handle
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return user account names. The bufptr parameter points to an array of USER_INFO_0 structures.
1 | Return detailed information about user accounts. The bufptr parameter points to an array of USER_INFO_1 structures.
2 | Return level one information and additional attributes about user accounts. The bufptr parameter points to an array of USER_INFO_2 structures.
3 | Return level two information and additional attributes about user accounts. This level is valid only on Windows NT/Windows 2000 servers. The bufptr parameter points to an array of USER_INFO_3 structures. Note that on Whistler and later, it is recommended that you use USER_INFO_4 instead.
4 | Whistler: Return level two information and additional attributes about user accounts. This level is valid only on Windows NT/Windows 2000 servers. The bufptr parameter points to an array of USER_INFO_4 structures.
10 | Return user and account names and comments. The bufptr parameter points to an array of USER_INFO_10 structures.
11 | Return detailed information about user accounts. The bufptr parameter points to an array of USER_INFO_11 structures.
20 | Return the user's name and identifier and various account attributes. The bufptr parameter points to an array of USER_INFO_20 structures. Note that on Whistler and later, it is recommended that you use USER_INFO_23 instead.
23 | Whistler: Return the user's name and identifier and various account attributes. The bufptr parameter points to an array of USER_INFO_23 structures.

filter
[in] Specifies a value that filters the account types for enumeration. A value of zero indicates all account types. This parameter can be one of the following values.
Value | Meaning
FILTER_TEMP_DUPLICATE_ACCOUNT | Enumerates local user account data on a domain controller.
FILTER_NORMAL_ACCOUNT | Enumerates global user account data on a computer.
FILTER_INTERDOMAIN_TRUST_ACCOUNT | Enumerates domain trust account data on a domain controller. The data is associated with the accounts of domains trusting the specified domain.
FILTER_WORKSTATION_TRUST_ACCOUNT | Enumerates workstation or member server account data on a domain controller.
FILTER_SERVER_TRUST_ACCOUNT | Enumerates domain controller account data on a domain controller.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length, in 8-bit bytes of returned data. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.

LAN Manager: If the call is to a computer that is running LAN Manager 2.x, the totalentries parameter will always reflect the total number of entries in the database no matter where it is in the resume sequence.

resume_handle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing user search. The handle should be zero on the first call and left unchanged for subsequent calls. If resume_handle is NULL, then no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.

Remarks

To retrieve the names and SIDs of domains trusted by a Local Security Authority (LSA) policy object, call the LsaEnumerateTrustedDomains function.

The NetUserEnum function does not return all system users. It returns only those users who have been added with a call to the NetUserAdd function. There is no guarantee that the list of users will be returned in sorted order.

If you call NetUserEnum and specify information level 1, 2, 3, or 4, the password member of each structure is set to NULL to maintain password security.

The following code sample demonstrates how to retrieve information about the user accounts on a server with a call to the NetUserEnum function. The sample calls NetUserEnum, specifying information level 0 (USER_INFO_0) to enumerate only global user accounts. If the call succeeds, the code loops through the entries and prints the name of each user account. Finally, the code sample frees the memory allocated for the information buffer and prints a total of the users enumerated.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPUSER_INFO_0 pBuf = NULL;
   LPUSER_INFO_0 pTmpBuf;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = -1;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD i;
   DWORD dwTotalCount = 0;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   wprintf(L"\nUser account on %s: \n", pszServerName);
   //
   // Call the NetUserEnum function, specifying level 0;
   //   enumerate global user account types only.
   //
   do // begin do
   {
      nStatus = NetUserEnum(pszServerName,
                            dwLevel,
                            FILTER_NORMAL_ACCOUNT, // global users
                            (LPBYTE*)&pBuf,
                            dwPrefMaxLen,
                            &dwEntriesRead,
                            &dwTotalEntries,
                            &dwResumeHandle);
      //
      // If the call succeeds,
      //
      if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
      {
         if ((pTmpBuf = pBuf) != NULL)
         {
            //
            // Loop through the entries.
            //
            for (i = 0; (i < dwEntriesRead); i++)
            {
               assert(pTmpBuf != NULL);

               if (pTmpBuf == NULL)
               {
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               //  Print the name of the user account.
               //
               wprintf(L"\t-- %s\n", pTmpBuf->usri0_name);

               pTmpBuf++;
               dwTotalCount++;
            }
         }
      }
      //
      // Otherwise, print the system error.
      //
      else
         fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      //
      // Free the allocated buffer.
      //
      if (pBuf != NULL)
      {
         NetApiBufferFree(pBuf);
         pBuf = NULL;
      }
   }
   // Continue to call NetUserEnum while
   //  there are more entries.
   //
   while (nStatus == ERROR_MORE_DATA); // end do
   //
   // Check again for allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of users enumerated.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

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. For more information, see IADsUser and IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, NetQueryDisplayInformation, NetUserGetGroups, NetUserGetInfo, NetUserAdd, USER_INFO_0, USER_INFO_1, USER_INFO_2, USER_INFO_4, USER_INFO_10, USER_INFO_11, USER_INFO_23, LsaEnumerateTrustedDomains


NetUserGetGroups

The NetUserGetGroups function retrieves a list of global groups to which a specified user belongs.

Security Requirements

Windows NT: No special group membership is required to successfully execute the NetUserGetGroups function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserGetGroups(
  LPCWSTR servername,
  LPCWSTR username,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
username
[in] Pointer to a constant Unicode string specifying the name of the user to search for in each group account.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Return the names of the global groups to which the user belongs. The bufptr parameter points to an array of GROUP_USERS_INFO_0 structures.

bufptr
[out] Pointer to the buffer that receives the data. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually retrieved.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been retrieved.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

Remarks

To retrieve a list of the local groups to which a user belongs, you can call the NetUserGetLocalGroups function. Network groups are separate and distinct from Windows NT/Windows 2000 system groups.

The following code sample demonstrates how to retrieve a list of global groups to which a user belongs with a call to the NetUserGetGroups function. The sample calls NetUserGetGroups, specifying information level 0 (GROUP_USERS_INFO_0). The code loops through the entries and prints the name of the global groups in which the user has membership. The sample also prints the total number of entries that are available and the number of entries actually enumerated if they do not match. Finally, the code sample frees the memory allocated for the buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPGROUP_USERS_INFO_0 pBuf = NULL;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = -1;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserGetGroups function, specifying level 0.
   //
   nStatus = NetUserGetGroups(argv[1],
                              argv[2],
                              dwLevel,
                              (LPBYTE*)&pBuf,
                              dwPrefMaxLen,
                              &dwEntriesRead,
                              &dwTotalEntries);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPGROUP_USERS_INFO_0 pTmpBuf;
      DWORD i;
      DWORD dwTotalCount = 0;

      if ((pTmpBuf = pBuf) != NULL)
      {
         fprintf(stderr, "\nGlobal group(s):\n");
         //
         // Loop through the entries;
         //  print the name of the global groups
         //  to which the user belongs.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }

            wprintf(L"\t-- %s\n", pTmpBuf->grui0_name);

            pTmpBuf++;
            dwTotalCount++;
         }
      }
      //
      // If all available entries were
      //  not enumerated, print the number actually
      //  enumerated and the total number available.
      //
      if (dwEntriesRead < dwTotalEntries)
         fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
      //
      // Otherwise, just print the total.
      //
      printf("\nEntries enumerated: %d\n", dwTotalCount);
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated buffer.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

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. For more information, see IADsUser and IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, GROUP_USERS_INFO_0, NetUserGetInfo, NetGroupGetUsers, NetUserGetLocalGroups, NetQueryDisplayInformation


NetUserGetInfo

The NetUserGetInfo function retrieves information about a particular user account on a server.

Security Requirements

Windows NT: No special group membership is required to successfully execute the NetUserGetInfo function. This is a change from LAN Manager, which required membership in the Administrators or Account Operators local group to call this function at information levels above 0 (except for the user's own account, which could use level 11).

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserGetInfo(
  LPCWSTR servername,
  LPCWSTR username,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
username
[in] Pointer to a constant Unicode string containing the name of the user account for which to return information.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the user account name. The bufptr parameter points to a USER_INFO_0 structure.
1 | Return detailed information about the user account. The bufptr parameter points to a USER_INFO_1 structure.
2 | Return level one information and additional attributes about the user account. The bufptr parameter points to a USER_INFO_2 structure.
3 | Return level two information and additional attributes about the user account. This level is valid only on Windows NT/Windows 2000 servers. The bufptr parameter points to a USER_INFO_3 structure. Note that on Whistler and later, it is recommended that you use USER_INFO_4 instead.
4 | Whistler: Return level two information and additional attributes about the user account. This level is valid only on Windows NT/Windows 2000 servers. The bufptr parameter points to a USER_INFO_4 structure.
10 | Return user and account names and comments. The bufptr parameter points to a USER_INFO_10 structure.
11 | Return detailed information about the user account. The bufptr parameter points to a USER_INFO_11 structure.
20 | Return the user's name and identifier and various account attributes. The bufptr parameter points to a USER_INFO_20 structure. Note that on Whistler and later, it is recommended that you use USER_INFO_23 instead.
23 | Whistler: Return the user's name and identifier and various account attributes. The bufptr parameter points to a USER_INFO_23 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

Remarks

The following code sample demonstrates how to retrieve information about a particular user account with a call to the NetUserGetInfo function. The sample calls NetUserGetInfo, specifying information level 10 (USER_INFO_10). If the call succeeds, the code prints information about the user account. Finally, the sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 10;
   LPUSER_INFO_10 pBuf = NULL;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserGetInfo function; specify level 10.
   //
   nStatus = NetUserGetInfo(argv[1],
                            argv[2],
                            dwLevel,
                            (LPBYTE *)&pBuf);
   //
   // If the call succeeds, print the user information.
   //
   if (nStatus == NERR_Success)
   {
    if (pBuf != NULL)
      {
         wprintf(L"\n\tAccount:      %s\n", pBuf->usri10_name);
         wprintf(L"\tComment:      %s\n", pBuf->usri10_comment);
         wprintf(L"\tUser comment: %s\n", pBuf->usri10_usr_comment);
         wprintf(L"\tFull name:    %s\n", pBuf->usri10_full_name);
      }
   }
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

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. For more information, see IADsUser and IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, NetUserSetInfo, NetUserGetGroups, NetUserEnum, USER_INFO_0, USER_INFO_1, USER_INFO_2, USER_INFO_4, USER_INFO_10, USER_INFO_11, USER_INFO_23


NetUserGetLocalGroups

The NetUserGetLocalGroups function retrieves a list of local groups to which a specified user belongs.

Security Requirements

Windows NT: Only authenticated users can successfully execute the NetUserGetLocalGroups function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserGetLocalGroups(
  LPCWSTR servername,
  LPCWSTR username,
  DWORD level,
  DWORD flags,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
username
[in] Pointer to a constant Unicode string specifying the name of the user for which to return local group membership information. If the string is of the form DomainName\UserName the user name is expected to be found on that domain. If the string is of the form UserName, the user name is expected to be found on the server specified by the servername parameter.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Return the names of the local groups to which the user belongs. The bufptr parameter points to an array of LOCALGROUP_USERS_INFO_0 structures.

flags
[in] Specifies a bitmask of flags. Currently, only the value LG_INCLUDE_INDIRECT is defined. If this bit is set, the function also returns the names of the local groups in which the user is indirectly a member (that is, the user has membership in a global group that is itself a member of one or more local groups).
bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

Remarks

To retrieve a list of global groups to which a specified user belongs, you can call the NetUserGetGroups function.

The following code sample demonstrates how to retrieve a list of the local groups to which a user belongs with a call to the NetUserGetLocalGroups function. The sample calls NetUserGetLocalGroups, specifying information level 0 (LOCALGROUP_USERS_INFO_0). The sample loops through the entries and prints the name of each local group in which the user has membership. If all available entries are not enumerated, it also prints the number of entries actually enumerated and the total number of entries available. Finally, the code sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPLOCALGROUP_USERS_INFO_0 pBuf = NULL;
   DWORD dwLevel = 0;
   DWORD dwFlags = LG_INCLUDE_INDIRECT ;
   DWORD dwPrefMaxLen = -1;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   //
   // Call the NetUserGetLocalGroups function
   //  specifying information level 0.
   //
   //  The LG_INCLUDE_INDIRECT flag specifies that the
   //   function should also return the names of the local
   //   groups in which the user is indirectly a member.
   //
   nStatus = NetUserGetLocalGroups(argv[1],
                                   argv[2],
                                   dwLevel,
                                   dwFlags,
                                   (LPBYTE *) &pBuf,
                                   dwPrefMaxLen,
                                   &dwEntriesRead,
                                   &dwTotalEntries);
   //
   // If the call succeeds,
   //
   if (nStatus == NERR_Success)
   {
      LPLOCALGROUP_USERS_INFO_0 pTmpBuf;
      DWORD i;
      DWORD dwTotalCount = 0;

      if ((pTmpBuf = pBuf) != NULL)
      {
         fprintf(stderr, "\nLocal group(s):\n");
         //
         // Loop through the entries and
         //  print the names of the local groups
         //  to which the user belongs.
         //
         for (i = 0; i < dwEntriesRead; i++)
         {
            assert(pTmpBuf != NULL);

            if (pTmpBuf == NULL)
            {
               fprintf(stderr, "An access violation has occurred\n");
               break;
            }

            wprintf(L"\t-- %s\n", pTmpBuf->lgrui0_name);

            pTmpBuf++;
            dwTotalCount++;
         }
      }
         //
         // If all available entries were
         //  not enumerated, print the number actually
         //  enumerated and the total number available.
         //
      if (dwEntriesRead < dwTotalEntries)
         fprintf(stderr, "\nTotal entries: %d", dwTotalEntries);
      //
      // Otherwise, just print the total.
      //
      printf("\nEntries enumerated: %d\n", dwTotalCount);
   }
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

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. For more information, see IADsUser and IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, NetUserGetGroups, LOCALGROUP_USERS_INFO_0


NetUserModalsGet

The NetUserModalsGet function retrieves global information for all users and global groups in the security database.

Security Requirements

Windows NT: Typically, authenticated users can successfully execute the NetUserModalsGet function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserModalsGet(
  LPCWSTR servername,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used. For more information, see the following Remarks section.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return global password parameters. The bufptr parameter points to a USER_MODALS_INFO_0 structure.
1 | Return logon server and domain controller information. The bufptr parameter points to a USER_MODALS_INFO_1 structure.
2 | Return domain name and identifier. The bufptr parameter points to a USER_MODALS_INFO_2 structure. For more information, see the following Remarks section.
3 | Return lockout information. The bufptr parameter points to a USER_MODALS_INFO_3 structure.

A null session logon can call NetUserModalsGet anonymously at information levels 0 and 3.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.

Remarks

To retrieve the SID of the domain to which the computer belongs, call the NetUserModalsGet function specifying a USER_MODALS_INFO_2 structure and NULL in the servername parameter. If the computer isn't a member of a domain, the function returns a NULL pointer.

The following code sample demonstrates how to retrieve global information for all users and global groups with a call to the NetUserModalsGet function. The sample calls NetUserModalsGet, specifying information level 0 (USER_MODALS_INFO_0). If the call succeeds, the sample prints global password information. Finally, the code sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 0;
   USER_MODALS_INFO_0 *pBuf = NULL;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   //
   // Call the NetUserModalsGet function; specify level 0.
   //
   nStatus = NetUserModalsGet(pszServerName,
                              dwLevel,
                              (LPBYTE *)&pBuf);
   //
   // If the call succeeds, print the global information.
   //
   if (nStatus == NERR_Success)
   {
      if (pBuf != NULL)
      {
         printf("\tMinimum password length:  %d\n", pBuf->usrmod0_min_passwd_len);
         printf("\tMaximum password age (d): %d\n", pBuf->usrmod0_max_passwd_age/86400);
         printf("\tMinimum password age (d): %d\n", pBuf->usrmod0_min_passwd_age/86400);
         printf("\tForced log off time (s):  %d\n", pBuf->usrmod0_force_logoff);
         printf("\tPassword history length:  %d\n", pBuf->usrmod0_password_hist_len);
      }
   }
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

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 modal functions. For more information, see IADsDomain.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Modals Functions, NetUserModalsSet, USER_MODALS_INFO_0, USER_MODALS_INFO_1, USER_MODALS_INFO_2, USER_MODALS_INFO_3


NetUserModalsSet

The NetUserModalsSet function sets global information for all users and global groups in the security database.

Security Requirements

Windows NT: Typically, only members of the Administrators, Domain Admins, or Enterprise Admins groups can successfully execute the NetUserModalsSet function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserModalsSet(
  LPCWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies global password parameters. The buf parameter points to a USER_MODALS_INFO_0 structure.
1 | Specifies logon server and domain controller information. The buf parameter points to a USER_MODALS_INFO_1 structure.
2 | Specifies the domain name and identifier. The buf parameter points to a USER_MODALS_INFO_2 structure.
3 | Specifies lockout information. The buf parameter points to a USER_MODALS_INFO_3 structure.
1001 | Specifies the minimum allowable password length. The buf parameter points to a USER_MODALS_INFO_1001 structure.
1002 | Specifies the maximum allowable password age. The buf parameter points to a USER_MODALS_INFO_1002 structure.
1003 | Specifies the minimum allowable password age. The buf parameter points to a USER_MODALS_INFO_1003 structure.
1004 | Specifies forced logoff information. The buf parameter points to a USER_MODALS_INFO_1004 structure.
1005 | Specifies the length of the password history. The buf parameter points to a USER_MODALS_INFO_1005 structure.
1006 | Specifies the role of the logon server. The buf parameter points to a USER_MODALS_INFO_1006 structure.
1007 | Specifies domain controller information. The buf parameter points to a USER_MODALS_INFO_1007 structure.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the information structure that causes ERROR_INVALID_PARAMETER. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | The specified parameter is invalid. For more information, see the following Remarks section.
NERR_InvalidComputer | The computer name is invalid.
NERR_UserNotFound | The user name could not be found.

Remarks

If the NetUserModalsSet function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the information structure that is invalid. (The information structure begins with USER_MODALS_INFO_ and its format is specified by the level parameter.) The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error. (The prefix usrmod*_ indicates that the member can begin with multiple prefixes, for example, usrmod2_ or usrmod1002_.)

Value | Member
MODALS_MIN_PASSWD_LEN_PARMNUM | usrmod*_min_passwd_len
MODALS_MAX_PASSWD_AGE_PARMNUM | usrmod*_max_passwd_age
MODALS_MIN_PASSWD_AGE_PARMNUM | usrmod*_min_passwd_age
MODALS_FORCE_LOGOFF_PARMNUM | usrmod*_force_logoff
MODALS_PASSWD_HIST_LEN_PARMNUM | usrmod*_password_hist_len
MODALS_ROLE_PARMNUM | usrmod*_role
MODALS_PRIMARY_PARMNUM | usrmod*_primary
MODALS_DOMAIN_NAME_PARMNUM | usrmod*_domain_name
MODALS_DOMAIN_ID_PARMNUM | usrmod*_domain_id
MODALS_LOCKOUT_DURATION_PARMNUM | usrmod*_lockout_duration
MODALS_LOCKOUT_OBSERVATION_WINDOW_PARMNUM | usrmod*_lockout_observation_window
MODALS_LOCKOUT_THRESHOLD_PARMNUM | usrmod*_lockout_threshold

The following code sample demonstrates how to set the global information for all users and global groups with a call to the NetUserModalsSet function. The sample fills in the members of the USER_MODALS_INFO_0 structure and calls NetUserModalsSet, specifying information level 0.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 0;
   USER_MODALS_INFO_0 ui;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   //
   // Fill in the USER_MODALS_INFO_0 structure.
   //
   ui.usrmod0_min_passwd_len = 0;
   ui.usrmod0_max_passwd_age = (86400 * 30);
   ui.usrmod0_min_passwd_age = 0;
   ui.usrmod0_force_logoff = TIMEQ_FOREVER; // never force logoff
   ui.usrmod0_password_hist_len = 0;
   //
   // Call the NetUserModalsSet function; specify level 0.
   //
   nStatus = NetUserModalsSet(pszServerName,
                              dwLevel,
                              (LPBYTE)&ui,
                              NULL);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Modals information set successfully on %s\n", argv[1]);
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

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 modal functions. For more information, see IADsDomain.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Modals Functions, NetUserModalsGet, USER_MODALS_INFO_0, USER_MODALS_INFO_1, USER_MODALS_INFO_2, USER_MODALS_INFO_3, USER_MODALS_INFO_1001, USER_MODALS_INFO_1002, USER_MODALS_INFO_1003, USER_MODALS_INFO_1004, USER_MODALS_INFO_1005, USER_MODALS_INFO_1006, USER_MODALS_INFO_1007


NetUserSetGroups

The NetUserSetGroups function sets global group memberships for a specified user account.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetUserSetGroups function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserSetGroups(
  LPCWSTR servername,
  LPCWSTR username,
  DWORD level,
  LPBYTE buf,
  DWORD num_entries
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
username
[in] Pointer to a constant Unicode string specifying the name of the user for which to set global group memberships.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | The buf parameter points to an array of GROUP_USERS_INFO_0 structures that specifies global group names.

buf
[in] Pointer to the buffer that specifies the data.
num_entries
[in] Specifies the number of entries contained in the array pointed to by the buf parameter.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_GroupNotFound | The group specified by the grui0_name member does not exist.
NERR_UserNotFound | The user name could not be found.

Remarks

To grant a user membership in one existing global group, you can call the NetGroupAddUser function.

The following code sample demonstrates how to set global group memberships for a user account with a call to the NetUserSetGroups function. The code sample fills in the grui0_name member of the GROUP_USERS_INFO_0 structure and calls NetUserSetGroups, specifying information level 0.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 0;
   GROUP_USERS_INFO_0 gi;
   NET_API_STATUS nStatus;

   if (argc != 4)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName GroupName\n", argv[0]);
      exit(1);
   }
   //
   // Fill in the GROUP_USERS_INFO_0 structure member.
   //
   gi.grui0_name = argv[3];
   //
   // Call the NetUserSetGroups function; specify level 0.
   //
   nStatus = NetUserSetGroups(argv[1],
                              argv[2],
                              dwLevel,
                              (LPBYTE)&gi,
                              1);
   //
   // If the call succeeds, inform the user.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Group membership has been successful for %s\n", argv[2]);
   //
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

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. For more information, see IADsUser and IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, NetUserGetGroups, NetGroupAddUser, GROUP_USERS_INFO_0


NetUserSetInfo

The NetUserSetInfo function sets the parameters of a user account.

Security Requirements

Windows NT: Only members of the Administrators or Account Operators local group can successfully execute the NetUserSetInfo function on a remote server or on a computer that has local security enabled. A user can call NetUserSetInfo to set certain information on his or her own account. For more information about permissions required to set user elements, see the following Remarks section.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits only Administrators and account operators to call this function. On a member server or workstation, only Administrators and account operators can call this function. For more information, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetUserSetInfo(
  LPCWSTR servername,
  LPCWSTR username,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a constant Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
username
[in] Pointer to a constant Unicode string specifying the name of the user account for which to set information.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Specifies the user account name. The buf parameter points to a USER_INFO_0 structure. Use this structure to specify a new group name. For more information, see the following Remarks section.
1 | Specifies detailed information about the user account. The buf parameter points to a USER_INFO_1 structure.
2 | Specifies level one information and additional attributes about the user account. The buf parameter points to a USER_INFO_2 structure.
3 | Specifies level two information and additional attributes about the user account. This level is valid only on Windows NT/Windows 2000 servers. The buf parameter points to a USER_INFO_3 structure. Note that on Whistler and later, it is recommended that you use USER_INFO_4 instead.
4 | Whistler: Specifies level two information and additional attributes about the user account. This level is valid only on Windows NT/Windows 2000 servers. The buf parameter points to a USER_INFO_4 structure.
21 | Specifies a one-way encrypted LAN Manager 2.x-compatible password. The buf parameter points to a USER_INFO_21 structure.
22 | Specifies detailed information about the user account. The buf parameter points to a USER_INFO_22 structure.
1003 | Specifies a user password. The buf parameter points to a USER_INFO_1003 structure.
1005 | Specifies a user privilege level. The buf parameter points to a USER_INFO_1005 structure.
1006 | Specifies the path of the home directory for the user. The buf parameter points to a USER_INFO_1006 structure.
1007 | Specifies a comment to associate with the user account. The buf parameter points to a USER_INFO_1007 structure.
1008 | Specifies user account attributes. The buf parameter points to a USER_INFO_1008 structure.
1009 | Specifies the path for the user's logon script file. The buf parameter points to a USER_INFO_1009 structure.
1010 | Specifies the user's operator privileges. The buf parameter points to a USER_INFO_1010 structure.
1011 | Specifies the full name of the user. The buf parameter points to a USER_INFO_1011 structure.
1012 | Specifies a comment to associate with the user. The buf parameter points to a USER_INFO_1012 structure.
1014 | Specifies the names of workstations from which the user can log on. The buf parameter points to a USER_INFO_1014 structure.
1017 | Specifies when the user account expires. The buf parameter points to a USER_INFO_1017 structure.
1020 | Specifies the times during which the user can log on. The buf parameter points to a USER_INFO_1020 structure.
1024 | Specifies the user's country/region code. The buf parameter points to a USER_INFO_1024 structure.
1051 | Specifies the relative identifier of a global group that represents the enrolled user. The buf parameter points to a USER_INFO_1051 structure.
1052 | Specifies the path to a network user's profile. The buf parameter points to a USER_INFO_1052 structure.
1053 | Specifies the drive letter assigned to the user's home directory. The buf parameter points to a USER_INFO_1053 structure.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the user information structure that causes ERROR_INVALID_PARAMETER. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid. For more information, see the following Remarks section.
NERR_InvalidComputer | The computer name is invalid.
NERR_NotPrimary | The operation is allowed only on the primary domain controller of the domain.
NERR_SpeGroupOp | The operation is not allowed on specified special groups, which are user groups, admin groups, local groups, or guest groups.
NERR_LastAdmin | The operation is not allowed on the last administrative account.
NERR_BadPassword | The share name or password is invalid.
NERR_PasswordTooShort | The password is shorter than required. (The password could also be too long, be too recent in its change history, not have enough unique characters, or not meet another password policy requirement.)
NERR_UserNotFound | The user name could not be found.

Remarks

See the end of this Remarks section for a code sample that demonstrates use of the NetUserSetInfo function.

Only users or applications having administrative privileges can call the NetUserSetInfo function to change a user's password. When an administrator calls NetUserSetInfo, the only restriction applied is that the new password length must be consistent with system modals. A user or application that knows a user's current password can call the NetUserChangePassword function to change the password.

Members of the Administrators local group can set any modifiable user account elements. All users can set the usri2_country_code member of the USER_INFO_2 structure (and the usri1024_country_code member of the USER_INFO_1024 structure) for their own accounts.

A member of the Account Operator's local group cannot set details for an Administrators class account, give an existing account Administrator privilege, or change the operator privilege of any account. If you attempt to change the privilege level or disable the last account with Administrator privilege in the security database, the NetUserSetInfo function fails and returns NERR_LastAdmin.

The correct way to specify the new name for an account is to call NetUserSetInfo with USER_INFO_0 and to specify the new value using the usri0_name member. If you call NetUserSetInfo with other information levels and specify a value using a usriX_name member, the value is ignored.

Note that calls to NetUserSetInfo can change the home directory only for user accounts that the network server creates.

If the NetUserSetInfo function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the user information structure that is invalid. (A user information structure begins with USER_INFO_ and its format is specified by the level parameter.) The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error. (The prefix usri*_ indicates that the member can begin with multiple prefixes, for example, usri10_ or usri1003_.)

Value | Member
USER_NAME_PARMNUM | usri*_name
USER_PASSWORD_PARMNUM | usri*_password
USER_PASSWORD_AGE_PARMNUM | usri*_password_age
USER_PRIV_PARMNUM | usri*_priv
USER_HOME_DIR_PARMNUM | usri*_home_dir
USER_COMMENT_PARMNUM | usri*_comment
USER_FLAGS_PARMNUM | usri*_flags
USER_SCRIPT_PATH_PARMNUM | usri*_script_path
USER_AUTH_FLAGS_PARMNUM | usri*_auth_flags
USER_FULL_NAME_PARMNUM | usri*_full_name
USER_USR_COMMENT_PARMNUM | usri*_usr_comment
USER_PARMS_PARMNUM | usri*_parms
USER_WORKSTATIONS_PARMNUM | usri*_workstations
USER_LAST_LOGON_PARMNUM | usri*_last_logon
USER_LAST_LOGOFF_PARMNUM | usri*_last_logoff
USER_ACCT_EXPIRES_PARMNUM | usri*_acct_expires
USER_MAX_STORAGE_PARMNUM | usri*_max_storage
USER_UNITS_PER_WEEK_PARMNUM | usri*_units_per_week
USER_LOGON_HOURS_PARMNUM | usri*_logon_hours
USER_PAD_PW_COUNT_PARMNUM | usri*_bad_pw_count
USER_NUM_LOGONS_PARMNUM | usri*_num_logons
USER_LOGON_SERVER_PARMNUM | usri*_logon_server
USER_COUNTRY_CODE_PARMNUM | usri*_country_code
USER_CODE_PAGE_PARMNUM | usri*_code_page
USER_PRIMARY_GROUP_PARMNUM | usri*_primary_group_id
USER_PROFILE_PARMNUM | usri*_profile
USER_HOME_DIR_DRIVE_PARMNUM | usri*_home_dir_drive

The following code sample demonstrates how to disable a user account with a call to the NetUserSetInfo function. The code sample fills in the usri1008_flags member of the USER_INFO_1008 structure, specifying the value UF_ACCOUNTDISABLE. Then the sample calls NetUserSetInfo, specifying information level 0.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 1008;
   USER_INFO_1008 ui;
   NET_API_STATUS nStatus;

   if (argc != 3)
   {
      fwprintf(stderr, L"Usage: %s \\\\ServerName UserName\n", argv[0]);
      exit(1);
   }
   // Fill in the USER_INFO_1008 structure member.
   // UF_SCRIPT: required for LAN Manager 2.0 and
   //  Windows NT/Windows 2000.
   //
   ui.usri1008_flags = UF_SCRIPT | UF_ACCOUNTDISABLE;
   //
   // Call the NetUserSetInfo function
   //  to disable the account, specifying level 1008.
   //
   nStatus = NetUserSetInfo(argv[1],
                            argv[2],
                            dwLevel,
                            (LPBYTE)&ui,
                            NULL);
   //
   // Display the result of the call.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"User account %s has been disabled\n", argv[2]);
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

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. For more information, see IADsUser and IADsComputer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, User Functions, NetUserGetInfo, USER_INFO_0, USER_INFO_1, USER_INFO_2, USER_INFO_4, USER_INFO_21, USER_INFO_22, USER_INFO_1003, USER_INFO_1005, USER_INFO_1006, USER_INFO_1007, USER_INFO_1008, USER_INFO_1009, USER_INFO_1010, USER_INFO_1011, USER_INFO_1012, USER_INFO_1013, USER_INFO_1014, USER_INFO_1017, USER_INFO_1020, USER_INFO_1024, USER_INFO_1051, USER_INFO_1052, USER_INFO_1053


NetValidateName

The NetValidateName function verifies the validity of a computer name, workgroup name, or domain name.

Security Requirements

No special group membership is required to successfully execute the NetValidateName function.

NET_API_STATUS NetValidateName(
  LPCWSTR lpServer,
  LPCWSTR lpName,
  LPCWSTR lpAccount,
  LPCWSTR lpPassword,
  NETSETUP_NAME_TYPE NameType
);

Parameters

lpServer
[in] Pointer to a constant null-terminated Unicode character string that specifies the name of the computer on which to call the function. If this parameter is NULL, the local computer is used.
lpName
[in] Pointer to a constant null-terminated Unicode character string that specifies the computer name, workgroup name, or domain name to validate.
lpAccount
[in] If the lpName parameter is a domain name, this parameter points to an account name to use when connecting to the domain controller. The string must specify either a domain NetBIOS name and user account (for example, "REDMOND\user") or the user principal name (UPN) of the user in the form of an Internet-style login name (for example, "someone@microsoft.com"). If this parameter is NULL, the caller's context is used.
lpPassword
[in] If the lpAccount parameter specifies an account name, this parameter must point to the password to use when connecting to the domain controller. Otherwise, this parameter must be NULL.
NameType
[in] Specifies the type of validation to perform. This parameter must be one of the following values.
typedef enum  _NETSETUP_NAME_TYPE {

    NetSetupUnknown = 0,
    NetSetupMachine,
    NetSetupWorkgroup,
    NetSetupDomain,
    NetSetupNonExistentDomain,
#if(_WIN32_WINNT >= 0x0500)
    NetSetupDnsMachine
#endif

} NETSETUP_NAME_TYPE, *PNETSETUP_NAME_TYPE;

These values have the following meanings.
Value | Meaning
NetSetupMachine | Verify that the NetBIOS computer name is valid and that it is not in use.
NetSetupWorkgroup | Verify that the workgroup name is valid.
NetSetupDomain | Verify that the domain name exists and that it is a domain.
NetSetupNonExistentDomain | Verify that the domain name is not in use.
NetSetupDnsMachine | Verify that the DNS computer name is valid.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_PARAMETER | A parameter is incorrect.
ERROR_DUP_NAME | A duplicate name already exists on the network.
ERROR_NO_SUCH_DOMAIN | The specified domain did not exist.
NERR_InvalidWorkgroupName | The specified workgroup name is not valid.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmjoin.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions


NetWkstaGetInfo

The NetWkstaGetInfo function returns information about the configuration of a workstation.

Security Requirements

Windows NT: You must have Print or Server operator privilege, or be a member of the Administrator or Account local groups to successfully execute the NetWkstaGetInfo function.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetWkstaGetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
100 | Return information about the workstation environment, including platform-specific information, the name of the domain and the local computer, and information concerning the operating system. The bufptr parameter points to a WKSTA_INFO_100 structure.
101 | In addition to level 100 information, return the path to the LANMAN directory. The bufptr parameter points to a WKSTA_INFO_101 structure.
102 | In addition to level 101 information, return the number of users who are logged on to the local computer. The bufptr parameter points to a WKSTA_INFO_102 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The level parameter is invalid.

Remarks

The following code sample demonstrates how to retrieve information about the configuration elements for a workstation using a call to the NetWkstaGetInfo function. The sample calls NetWkstaGetInfo, specifying information level 102 (WKSTA_INFO_102). If the call succeeds, the sample prints information about the workstation. Finally, the code sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 102;
   LPWKSTA_INFO_102 pBuf = NULL;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;
   //
   // Check command line arguments.
   //
   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   //
   // Call the NetWkstaGetInfo function, specifying level 102.
   //
   nStatus = NetWkstaGetInfo(pszServerName,
                             dwLevel,
                             (LPBYTE *)&pBuf);
   //
   // If the call is successful,
   //  print the workstation data.
   //
   if (nStatus == NERR_Success)
   {
      printf("\n\tPlatform: %d\n", pBuf->wki102_platform_id);
      wprintf(L"\tName:     %s\n", pBuf->wki102_computername);
      printf("\tVersion:  %d.%d\n", pBuf->wki102_ver_major,
                                  pBuf->wki102_ver_minor);
      wprintf(L"\tDomain:   %s\n", pBuf->wki102_langroup);
      wprintf(L"\tLan Root: %s\n", pBuf->wki102_lanroot);
      wprintf(L"\t# Logged On Users: %d\n", pBuf->wki102_logged_on_users);
   }
   //
   // Otherwise, indicate the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Workstation and Workstation User Functions, NetWkstaSetInfo, WKSTA_INFO_100, WKSTA_INFO_101, WKSTA_INFO_102


NetWkstaSetInfo

The NetWkstaSetInfo function configures a workstation. The information remains in effect after the system has been reinitialized.

Security Requirements

Only members of the Administrators local group can successfully execute the NetWkstaSetInfo function on a remote server.

NET_API_STATUS NetWkstaSetInfo(
  LPWSTR servername,
  DWORD level,
  LPBYTE buffer,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
100 | Specifies information about a workstation environment, including platform-specific information, the names of the domain and the local computer, and information concerning the operating system. The buffer parameter points to a WKSTA_INFO_100 structure.
101 | In addition to level 100 information, specifies the path to the LANMAN directory. The buffer parameter points to a WKSTA_INFO_101 structure.
102 | In addition to level 101 information, specifies the number of users who are logged on to the local computer. The buffer parameter points to a WKSTA_INFO_102 structure.

Do not set levels 1010-1013, 1018, 1023, 1027, 1028, 1032, 1033, 1035, or 1041-1062. Level 502 is obsolete.

buffer
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first member of the workstation information structure that causes the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error. For more information, see the following Remarks section.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid. For more information, see the following Remarks section.

Remarks

See the end of this Remarks section for a code sample that demonstrates use of the NetWkstaSetInfo function.

You must be a member of the Administrators local group to successfully execute NetWkstaSetInfo on a remote server or on a computer that has local security enabled.

The NetWkstaSetInfo function does not change the values in the LANMAN.INI file. When the workstation service is stopped and restarted, workstation parameters are reset to the default values specified in the LANMAN.INI file (unless they are overwritten by command-line parameters). Values set by previous calls to NetWkstaSetInfo can be overwritten when workstation parameters are reset.

If the NetWkstaSetInfo function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the first member of the workstation information structure that is invalid. (A workstation information structure begins with WKSTA_INFO_ and its format is specified by the level parameter.) The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error. (The prefix wki*_ indicates that the member can begin with multiple prefixes, for example, wki100_ or wki402_.)

Value |  | Member
WKSTA_PLATFORM_ID_PARMNUM | wki*_platform_id
WKSTA_COMPUTERNAME_PARMNUM | wki*_computername
WKSTA_LANGROUP_PARMNUM | wki*_langroup
WKSTA_VER_MAJOR_PARMNUM | wki*_ver_major
WKSTA_VER_MINOR_PARMNUM | wki*_ver_minor
WKSTA_LOGGED_ON_USERS_PARMNUM | wki*_logged_on_users
WKSTA_LANROOT_PARMNUM | wki*_lanroot
WKSTA_LOGON_DOMAIN_PARMNUM | wki*_logon_domain
WKSTA_LOGON_SERVER_PARMNUM | wki*_logon_server
WKSTA_CHARWAIT_PARMNUM | wki*_char_wait
WKSTA_CHARTIME_PARMNUM | wki*_collection_time
WKSTA_CHARCOUNT_PARMNUM | wki*_maximum_collection_count
WKSTA_KEEPCONN_PARMNUM | wki*_keep_conn
WKSTA_KEEPSEARCH_PARMNUM | wki*_keep_search
WKSTA_MAXCMDS_PARMNUM | wki*_max_cmds
WKSTA_NUMWORKBUF_PARMNUM | wki*_num_work_buf
WKSTA_MAXWRKCACHE_PARMNUM | wki*_max_wrk_cache
WKSTA_SESSTIMEOUT_PARMNUM | wki*_sess_timeout
WKSTA_SIZERROR_PARMNUM | wki*_siz_error
WKSTA_NUMALERTS_PARMNUM | wki*_num_alerts
WKSTA_NUMSERVICES_PARMNUM | wki*_num_services
WKSTA_ERRLOGSZ_PARMNUM | wki*_errlog_sz
WKSTA_PRINTBUFTIME_PARMNUM | wki*_print_buf_time
WKSTA_NUMCHARBUF_PARMNUM | wki*_num_char_buf
WKSTA_SIZCHARBUF_PARMNUM | wki*_siz_char_buf
WKSTA_WRKHEURISTICS_PARMNUM | wki*_wrk_heuristics
WKSTA_MAILSLOTS_PARMNUM | wki*_mailslots
WKSTA_MAXTHREADS_PARMNUM | wki*_max_threads
WKSTA_SIZWORKBUF_PARMNUM | wki*_siz_work_buf
WKSTA_NUMDGRAMBUF_PARMNUM | wki*_num_dgram_buf

The following code sample demonstrates how to set the session time-out value associated with a workstation using a call to the NetServerSetInfo function. (The session time-out is the number of seconds the server waits before disconnecting an inactive session.) The code specifies information level 502 (WKSTA_INFO_502).

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPWKSTA_INFO_502 pBuf = NULL;
   WKSTA_INFO_502 wi;
   DWORD dwLevel = 502;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if ((argc < 2) || (argc > 3))
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName] SessionTimeOut\n", argv[0]);
      exit(1);
   }

   if (argc == 3)
      pszServerName = argv[1];
   //
   // Retrieve the current settings.
   //
   nStatus = NetWkstaGetInfo(pszServerName,
                             dwLevel,
                             (LPBYTE *)&pBuf);

   if (nStatus != NERR_Success)
   {
      fprintf(stderr, "A system error has occurred (NetWkstaGetInfo): %d\n", nStatus);
      return -1;
   }

   if (pBuf != NULL)
   {
      //
      // Copy the existing settings to the new structure,
      //   and free the buffer.
      //
      CopyMemory(&wi, pBuf, sizeof(wi));
      NetApiBufferFree(pBuf);
   }
   else
   {
      fprintf(stderr, "Memory invalid!\n");
      return -1;
   }
   //
   // Set a new session time-out value by
   //   calling the NetWkstaSetInfo function.
   //
   wi.wki502_sess_timeout = _wtoi(argv[argc-1]);
   nStatus = NetWkstaSetInfo(pszServerName,
                             dwLevel,
                             (LPBYTE)&wi,
                             NULL);
   //
   // Display the result of the call.
   //
   if (nStatus == NERR_Success)
      fwprintf(stderr, L"Workstation information reset: session time-out = %d\n", _wtoi(argv[argc-1]));
   else
      fprintf(stderr, "A system error has occurred (NetWkstaSetInfo): %d\n", nStatus);

   return 0;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Workstation and Workstation User Functions, NetWkstaGetInfo, WKSTA_INFO_100, WKSTA_INFO_101, WKSTA_INFO_102


NetWkstaTransportAdd

The NetWkstaTransportAdd function binds (or connects) the redirector to the transport. The redirector is the software on the client computer which generates file requests to the server computer.

Windows 2000 or later: This function is obsolete on Windows 2000. You can change the default settings for transport protocols manually through the Local Area Connection Properties dialog box in the Network and Dial-Up Connections folder.

Security Requirements

Only members of the Administrators local group can successfully execute the NetWkstaTransportAdd function.

NET_API_STATUS NetWkstaTransportAdd(
  LPWSTR servername,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Specifies workstation transport protocol information. The buf parameter points to a WKSTA_TRANSPORT_INFO_0 structure.

buf
[in] Pointer to the buffer that specifies the data. The format of this data depends on the value of the level parameter.
parm_err
[out] Pointer to a DWORD value that receives the index of the first parameter that causes the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_LEVEL | The level parameter, which indicates what level of data structure information is available, is invalid.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.

Remarks

If the NetWkstaTransportAdd function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the member of the WKSTA_TRANSPORT_INFO_0 structure that is invalid. The following table lists the values that can be returned in the parm_err parameter and the corresponding structure member that is in error.

Value | Member
TRANSPORT_QUALITYOFSERVICE_PARMNUM | wkti0_quality_of_service
TRANSPORT_NAME_PARMNUM | wkti0_transport_name

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server and Workstation Transport Functions, NetWkstaTransportDel, WKSTA_TRANSPORT_INFO_0


NetWkstaTransportDel

The NetWkstaTransportDel function unbinds the transport protocol from the redirector. (The redirector is the software on the client computer that generates file requests to the server computer.)

Windows 2000 or later: This function is obsolete on Windows 2000. You can change the default settings for transport protocols manually through the Local Area Connection Properties dialog box in the Network and Dial-Up Connections folder.

Security Requirements

Only members of the Administrators local group can successfully execute the NetWkstaTransportDel function.

NET_API_STATUS NetWkstaTransportDel(
  LPWSTR servername,
  LPWSTR transportname,
  DWORD ucond
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
transportname
[in] Pointer to a Unicode string specifying the name of the transport protocol to disconnect from the redirector.
ucond
[in] Specifies the level of force to use when disconnecting the transport protocol from the redirector. This parameter can be one of the following values.
Value | Meaning
USE_NOFORCE | Fail the disconnection if open files exist on the connection.
USE_FORCE | Fail the disconnection if open files exist on the connection.
USE_LOTS_OF_FORCE | Close any open files and delete the connection.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.
NERR_UseNotFound | The network connection does not exist.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server and Workstation Transport Functions, NetWkstaTransportAdd


NetWkstaTransportEnum

The NetWkstaTransportEnum function supplies information about transport protocols that are managed by the redirector, which is the software on the client computer that generates file requests to the server computer.

Security Requirements

No special group membership is required to successfully execute the NetWkstaTransportEnum function.

NET_API_STATUS NetWkstaTransportEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be the following value.
Value | Meaning
0 | Return workstation transport protocol information. The bufptr parameter points to an array of WKSTA_TRANSPORT_INFO_0 structures.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resumehandle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing workstation transport search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_INVALID_LEVEL | The level parameter, which indicates what level of data structure information is available, is invalid.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Server and Workstation Transport Functions, NetWkstaTransportAdd, NetWkstaTransportDel, WKSTA_TRANSPORT_INFO_0


NetWkstaUserEnum

The NetWkstaUserEnum function lists information about all users currently logged on to the workstation. This list includes interactive, service and batch logons.

Security Requirements

Windows NT: Only members of the Administrators local group can successfully execute NetWkstaUserEnum function both locally and on a remote server.

Windows 2000 or later: If you call this function on a Windows 2000 domain controller that is running Active Directory, access is allowed or denied based on the access-control list (ACL) for the securable object. The default ACL permits all authenticated users and members of the "Pre-Windows 2000 compatible access" group to view the information. By default, the "Pre-Windows 2000 compatible access" group includes Everyone as a member. This enables anonymous access to the information if the system allows anonymous access.

If you call this function on a Windows 2000 member server or workstation, all authenticated users can view the information. Anonymous access is also permitted if the RestrictAnonymous policy setting allows anonymous access.

For more information about restricting anonymous access, see Security Requirements for the Network Management Functions.

NET_API_STATUS NetWkstaUserEnum(
  LPWSTR servername,
  DWORD level,
  LPBYTE *bufptr,
  DWORD prefmaxlen,
  LPDWORD entriesread,
  LPDWORD totalentries,
  LPDWORD resumehandle
);

Parameters

servername
[in] Pointer to a Unicode string specifying the name of the remote server on which the function is to execute. The string must begin with \\. If this parameter is NULL, the local computer is used.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the names of users currently logged on to the workstation. The bufptr parameter points to an array of WKSTA_USER_INFO_0 structures.
1 | Return the names of the current users and the domains accessed by the workstation. The bufptr parameter points to an array of WKSTA_USER_INFO_1 structures.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function. Note that you must free the buffer even if the function fails with ERROR_MORE_DATA.
prefmaxlen
[in] Specifies the preferred maximum length of returned data, in bytes. If you specify MAX_PREFERRED_LENGTH, the function allocates the amount of memory required for the data. If you specify another value in this parameter, it can restrict the number of bytes that the function returns. If the buffer size is insufficient to hold all entries, the function returns ERROR_MORE_DATA. For more information, see Network Management Function Buffers and Network Management Function Buffer Lengths.
entriesread
[out] Pointer to a DWORD value that receives the count of elements actually enumerated.
totalentries
[out] Pointer to a DWORD value that receives the total number of entries that could have been enumerated from the current resume position.
resumehandle
[in/out] Pointer to a DWORD value that contains a resume handle which is used to continue an existing search. The handle should be zero on the first call and left unchanged for subsequent calls. If resumehandle is NULL, no resume handle is stored.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_ACCESS_DENIED | The user does not have access to the requested information.
ERROR_MORE_DATA | More entries are available. Specify a large enough buffer to receive all entries.
ERROR_INVALID_LEVEL | The level parameter is invalid.

Remarks

Note that since the NetWkstaUserEnum function lists entries for service and batch logons, as well as for interactive logons, the function can return entries for users who have logged off a workstation. This can occur, for example, when a user calls a service that impersonates the user. In this instance, NetWkstaUserEnum returns an entry for the user until the service stops impersonating the user.

The following code sample demonstrates how to list information about all users currently logged on to a workstation using a call to the NetWkstaUserEnum function. The sample calls NetWkstaUserEnum, specifying information level 0 (WKSTA_USER_INFO_0). The sample loops through the entries and prints the names of the users logged on to a workstation. Finally, the code sample frees the memory allocated for the information buffer, and prints the total number of users enumerated.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <assert.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   LPWKSTA_USER_INFO_0 pBuf = NULL;
   LPWKSTA_USER_INFO_0 pTmpBuf;
   DWORD dwLevel = 0;
   DWORD dwPrefMaxLen = -1;
   DWORD dwEntriesRead = 0;
   DWORD dwTotalEntries = 0;
   DWORD dwResumeHandle = 0;
   DWORD i;
   DWORD dwTotalCount = 0;
   NET_API_STATUS nStatus;
   LPTSTR pszServerName = NULL;

   if (argc > 2)
   {
      fwprintf(stderr, L"Usage: %s [\\\\ServerName]\n", argv[0]);
      exit(1);
   }
   // The server is not the default local computer.
   //
   if (argc == 2)
      pszServerName = argv[1];
   fwprintf(stderr, L"\nUsers currently logged on %s:\n", pszServerName);
   //
   // Call the NetWkstaUserEnum function, specifying level 0.
   //
   do // begin do
   {
      nStatus = NetWkstaUserEnum(pszServerName,
                                 dwLevel,
                                 (LPBYTE*)&pBuf,
                                 dwPrefMaxLen,
                                 &dwEntriesRead,
                                 &dwTotalEntries,
                                 &dwResumeHandle);
      //
      // If the call succeeds,
      //
      if ((nStatus == NERR_Success) || (nStatus == ERROR_MORE_DATA))
      {
         if ((pTmpBuf = pBuf) != NULL)
         {
            //
            // Loop through the entries.
            //
            for (i = 0; (i < dwEntriesRead); i++)
            {
               assert(pTmpBuf != NULL);

               if (pTmpBuf == NULL)
               {
                  //
                  // Only members of the Administrators local group
                  //  can successfully execute NetWkstaUserEnum
                  //  locally and on a remote server.
                  //
                  fprintf(stderr, "An access violation has occurred\n");
                  break;
               }
               //
               // Print the user logged on to the workstation.
               //
               wprintf(L"\t-- %s\n", pTmpBuf->wkui0_username);

               pTmpBuf++;
               dwTotalCount++;
            }
         }
      }
      //
      // Otherwise, indicate a system error.
      //
      else
         fprintf(stderr, "A system error has occurred: %d\n", nStatus);
      //
      // Free the allocated memory.
      //
      if (pBuf != NULL)
      {
         NetApiBufferFree(pBuf);
         pBuf = NULL;
      }
   }
   //
   // Continue to call NetWkstaUserEnum while
   //  there are more entries.
   //
   while (nStatus == ERROR_MORE_DATA); // end do
   //
   // Check again for allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);
   //
   // Print the final count of workstation users.
   //
   fprintf(stderr, "\nTotal of %d entries enumerated\n", dwTotalCount);

   return 0;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Workstation and Workstation User Functions, NetWkstaGetInfo, NetWkstaSetInfo, WKSTA_USER_INFO_0, WKSTA_USER_INFO_1


NetWkstaUserGetInfo

The NetWkstaUserGetInfo function returns information about the currently logged-on user. This function must be called in the context of the logged-on user.

Security Requirements

The NetWkstaUserGetInfo function only works locally.

NET_API_STATUS NetWkstaUserGetInfo(
  LPWSTR reserved,
  DWORD level,
  LPBYTE *bufptr
);

Parameters

reserved
This parameter must be set to NULL.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
0 | Return the name of the user currently logged on to the workstation. The bufptr parameter points to a WKSTA_USER_INFO_0 structure.
1 | Return information about the workstation, including the name of the current user and the domains accessed by the workstation. The bufptr parameter points to a WKSTA_USER_INFO_1 structure.
1101 | Return domains browsed by the workstation. The bufptr parameter points to a WKSTA_USER_INFO_1101 structure.

bufptr
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_NOT_ENOUGH_MEMORY | The system ran out of memory resources. Either the network manager configuration is incorrect, or the program is running on a system with insufficient memory.
ERROR_INVALID_LEVEL | The level parameter is invalid.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.

Remarks

The following code sample demonstrates how to retrieve information about the currently logged-on user using a call to the NetWkstaUserGetInfo function. The sample calls NetWkstaUserGetInfo, specifying information level 1 (WKSTA_USER_INFO_1). If the call succeeds, the sample prints information about the logged-on user. Finally, the sample frees the memory allocated for the information buffer.

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(void)
{
   DWORD dwLevel = 1;
   LPWKSTA_USER_INFO_1 pBuf = NULL;
   NET_API_STATUS nStatus;
   //
   // Call the NetWkstaUserGetInfo function;
   //  specify level 1.
   //
   nStatus = NetWkstaUserGetInfo(NULL,
                                 dwLevel,
                                 (LPBYTE *)&pBuf);
   //
   // If the call succeeds, print the information
   //  about the logged-on user.
   //
   if (nStatus == NERR_Success)
   {
      if (pBuf != NULL)
      {
         wprintf(L"\n\tUser:          %s\n", pBuf->wkui1_username);
         wprintf(L"\tDomain:        %s\n", pBuf->wkui1_logon_domain);
         wprintf(L"\tOther Domains: %s\n", pBuf->wkui1_oth_domains);
         wprintf(L"\tLogon Server:  %s\n", pBuf->wkui1_logon_server);
      }
   }
   // Otherwise, print the system error.
   //
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);
   //
   // Free the allocated memory.
   //
   if (pBuf != NULL)
      NetApiBufferFree(pBuf);

   return 0;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Workstation and Workstation User Functions, NetWkstaSetInfo, WKSTA_USER_INFO_0, WKSTA_USER_INFO_1, WKSTA_USER_INFO_1101


NetWkstaUserSetInfo

The NetWkstaUserSetInfo function sets the user-specific information about the configuration elements for a workstation.

Security Requirements

The NetWkstaUserSetInfo function only works locally.

NET_API_STATUS NetWkstaUserSetInfo(
  LPWSTR reserved,
  DWORD level,
  LPBYTE buf,
  LPDWORD parm_err
);

Parameters

reserved
This parameter must be set to zero.
level
[in] Specifies the information level of the data. This parameter can be one of the following values.
Value | Meaning
1 | Specifies information about the workstation, including the name of the current user and the domains accessed by the workstation. The buf parameter points to a WKSTA_USER_INFO_1 structure.
1101 | Specifies domains browsed by the workstation. The buf parameter points to a WKSTA_USER_INFO_1101 structure.

buf
[out] Pointer to the buffer that receives the data. The format of this data depends on the value of the level parameter. This buffer is allocated by the system and must be freed using the NetApiBufferFree function.
parm_err
[out] Pointer to a DWORD value that receives the index of the first parameter that causes the ERROR_INVALID_PARAMETER error. If this parameter is NULL, the index is not returned on error.

Return Values

If the function succeeds, the return value is NERR_Success.

If the function fails, the return value can be one of the following error codes.

Value | Meaning
ERROR_INVALID_LEVEL | The level parameter is invalid.
ERROR_INVALID_PARAMETER | One of the function parameters is invalid.

Remarks

Domain names in the wkui1101_oth_domains member of the WKSTA_USER_INFO_1101 structure are separated by spaces. An empty list is valid. A null pointer means to leave the member unmodified. The wkui1101_oth_domains member cannot be set with MS-DOS. When setting this element, NetWkstaUserSetInfo rejects the request if the name list was invalid or if a name could not be added to one or more of the network adapters managed by the system.

If the NetWkstaUserSetInfo function returns ERROR_INVALID_PARAMETER, you can use the parm_err parameter to indicate the member of the workstation user information structure that is invalid. (A workstation user information structure begins with WKSTA_USER_INFO_ and its format is specified by the level parameter.) The following table lists the value that can be returned in the parm_err parameter and the corresponding structure member that is in error. (The prefix wkui*_ indicates that the member can begin with multiple prefixes, for example, wkui0_ or wkui1_.)

Value | Member
WKSTA_OTH_DOMAINS_PARMNUM | wkui*_oth_domains

The following code sample demonstrates how to set user-specific information for a workstation using a call to the NetWkstaUserSetInfo function, specifying information level 1101 (WKSTA_USER_INFO_1101).

#ifndef UNICODE
#define UNICODE
#endif

#include <stdio.h>
#include <windows.h>
#include <lm.h>

int wmain(int argc, wchar_t *argv[])
{
   DWORD dwLevel = 1101;
   WKSTA_USER_INFO_1101 wui;
   NET_API_STATUS nStatus;

   if (argc != 2)
   {
      fwprintf(stderr, L"Usage: %s OtherDomains\n", argv[0]);
      exit(1);
   }
   //
   // Fill in the WKSTA_USER_INFO_1101 structure member.
   //
   wui.wkui1101_oth_domains = argv[1];
   //
   // Call the NetWkstaUserSetInfo function
   //  to change the list of domains browsed by
   //  the workstation; specify level 1101.
   //
   nStatus = NetWkstaUserSetInfo(NULL,
                                 dwLevel,
                                 (LPBYTE)&wui,
                                 NULL);
   //
   // Display the result of the call.
   //
   if (nStatus == NERR_Success)
      fprintf(stderr, "Workstation user information has been changed\n");
   else
      fprintf(stderr, "A system error has occurred: %d\n", nStatus);

   return 0;
}

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.
Library: Use Netapi32.lib.

See Also

Network Management Overview, Network Management Functions, Workstation and Workstation User Functions, NetWkstaUserGetInfo, WKSTA_USER_INFO_1, WKSTA_USER_INFO_1101


Network Management Structures

The network management structures can be grouped as follows.

Alert Structures

STD_ALERT
ADMIN_OTHER_INFO
ERRLOG_OTHER_INFO
PRINT_OTHER_INFO
USER_OTHER_INFO

Distributed File System (Dfs) Structures

DFS_INFO_1
DFS_INFO_2
DFS_INFO_3
DFS_INFO_4
DFS_INFO_100
DFS_INFO_101
DFS_INFO_102
DFS_INFO_200
DFS_STORAGE_INFO

File Structures

FILE_INFO_2
FILE_INFO_3

Get Structures

NET_DISPLAY_GROUP
NET_DISPLAY_MACHINE
NET_DISPLAY_USER

Group Structures

GROUP_INFO_0
GROUP_INFO_1
GROUP_INFO_2
GROUP_INFO_3
GROUP_INFO_1002
GROUP_INFO_1005
GROUP_USERS_INFO_0

Local Group Structures

LOCALGROUP_INFO_0
LOCALGROUP_INFO_1
LOCALGROUP_INFO_1002
LOCALGROUP_MEMBERS_INFO_0
LOCALGROUP_MEMBERS_INFO_1
LOCALGROUP_MEMBERS_INFO_2
LOCALGROUP_MEMBERS_INFO_3
LOCALGROUP_USERS_INFO_0

Message Structures

MSG_INFO_0
MSG_INFO_1

Remote Utility Structure

TIME_OF_DAY_INFO

Replicator Structures

REPL_EDIR_INFO_0
REPL_EDIR_INFO_1
REPL_EDIR_INFO_2
REPL_EDIR_INFO_1000
REPL_EDIR_INFO_1001
REPL_IDIR_INFO_0
REPL_IDIR_INFO_1
REPL_INFO_0
REPL_INFO_1000
REPL_INFO_1001
REPL_INFO_1002
REPL_INFO_1003

Schedule Structures

AT_ENUM
AT_INFO

Server Structures

SERVER_INFO_100
SERVER_INFO_101
SERVER_INFO_102
SERVER_INFO_402
SERVER_INFO_403
SERVER_INFO_1005
SERVER_INFO_1010
SERVER_INFO_1016
SERVER_INFO_1017
SERVER_INFO_1018
SERVER_INFO_1107
SERVER_INFO_1501
SERVER_INFO_1502
SERVER_INFO_1503
SERVER_INFO_1506
SERVER_INFO_1509
SERVER_INFO_1510
SERVER_INFO_1511
SERVER_INFO_1512
SERVER_INFO_1513
SERVER_INFO_1515
SERVER_INFO_1516
SERVER_INFO_1518
SERVER_INFO_1523
SERVER_INFO_1528
SERVER_INFO_1529
SERVER_INFO_1530
SERVER_INFO_1533
SERVER_INFO_1536
SERVER_INFO_1538
SERVER_INFO_1539
SERVER_INFO_1540
SERVER_INFO_1541
SERVER_INFO_1542
SERVER_INFO_1544
SERVER_INFO_1550
SERVER_INFO_1552

Server and Workstation Transport Structures

SERVER_TRANSPORT_INFO_0
SERVER_TRANSPORT_INFO_1
SERVER_TRANSPORT_INFO_2
SERVER_TRANSPORT_INFO_3
WKSTA_TRANSPORT_INFO_0

Session Structures

SESSION_INFO_0
SESSION_INFO_1
SESSION_INFO_2
SESSION_INFO_10
SESSION_INFO_502

Share Structures

CONNECTION_INFO_0
CONNECTION_INFO_1
SHARE_INFO_0
SHARE_INFO_1
SHARE_INFO_2
SHARE_INFO_501
SHARE_INFO_502
SHARE_INFO_1004
SHARE_INFO_1005
SHARE_INFO_1006
SHARE_INFO_1501

Statistics Structures

STAT_SERVER_0
STAT_WORKSTATION_0

Use Structures

USE_INFO_0
USE_INFO_1
USE_INFO_2

User Structures

USER_INFO_0
USER_INFO_1
USER_INFO_2
USER_INFO_3
USER_INFO_4
USER_INFO_10
USER_INFO_11
USER_INFO_20
USER_INFO_21
USER_INFO_22
USER_INFO_23
USER_INFO_1003
USER_INFO_1005
USER_INFO_1006
USER_INFO_1007
USER_INFO_1008
USER_INFO_1009
USER_INFO_1010
USER_INFO_1011
USER_INFO_1012
USER_INFO_1013
USER_INFO_1014
USER_INFO_1017
USER_INFO_1018
USER_INFO_1020
USER_INFO_1023
USER_INFO_1024
USER_INFO_1025
USER_INFO_1051
USER_INFO_1052
USER_INFO_1053

User Modals Structures

USER_MODALS_INFO_0
USER_MODALS_INFO_1
USER_MODALS_INFO_2
USER_MODALS_INFO_3
USER_MODALS_INFO_1001
USER_MODALS_INFO_1002
USER_MODALS_INFO_1003
USER_MODALS_INFO_1004
USER_MODALS_INFO_1005
USER_MODALS_INFO_1006
USER_MODALS_INFO_1007

Workstation and Workstation User Structures

WKSTA_INFO_100
WKSTA_INFO_101
WKSTA_INFO_102
WKSTA_USER_INFO_0
WKSTA_USER_INFO_1
WKSTA_USER_INFO_1101

In addition, the following network management structures are supported by Windows 95 and Windows 98.

Windows 95/98 Structures

access_info_0
access_info_1
access_list
connection_info_50
file_info_50
security_info_1
server_info_1
server_info_50
session_info_0
session_info_1
session_info_2
session_info_10
session_info_50
share_info_1
share_info_50


access_info_0

Windows 95/98/Me: The access_info_0 structure contains the name of a resource.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000.

struct _access_info_0 {
  char FAR *acc0_resource_name;
};

Members

acc0_resource_name
Pointer to a string specifying the name of a resource. The following resource types are valid.
Resource type | Required format
Disk drive | drive:
Path | \path
Directory | drive:\pathname
File | drive:\pathname
UNC | \\server\sharename\path
Pipe | \pipe\pipename
Printer queue | \print\queuename

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Access Functions, NetAccessEnum, NetAccessGetInfo, access_info_1


access_info_1

Windows 95/98/Me: The access_info_1 structure contains the name of a resource, auditing attributes for the resource, and the number of resource permission structures that follow the structure.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000.

struct _access_info_1 {
  char FAR *      acc1_resource_name;
  short           acc1_attr;
  short           acc1_count;
};

Members

acc1_resource_name
Pointer to a string specifying the name of the resource. The following resource types are valid.
Resource type | Required format
Disk drive | drive:
Path | \path
Directory | drive:\pathname
File | drive:\pathname
UNC | \\server\sharename\path
Pipe | \pipe\pipename
Printer queue | \print\queuename

acc1_attr
Specifies a SHORT variable that indicates whether auditing of access events is required for the resource identified by the acc1_resource_name member.

If this member is equal to 1 or to the value ACCESS_AUDIT, it indicates that all access events should be audited. If this member is equal to 0, no auditing is required. Other values indicate auditing of specific access events, as listed in the following table.
Bit | File event | Directory event
0 | Audit all access events. When you set this bit, all access attempts are audited. Any other bits you set are ignored. | Same as the file event.
1-2 | Reserved; must be zero. | Reserved; must be zero.
3 | Ignored. | Reserved.
4 | Successful opens. | Reserved.
5 | Successful writes. | Successful creates.
6 | Successful deletes and truncates. | Successful deletes.
7 | Successful ACL changes. | Same as the file event.
8 | Failed opens. | Reserved.
9 | Failed writes. | Failed creates.
10 | Failed deletes and truncates. | Failed deletes.
11 | Failed ACL changes. | Same as the file event.
12-15 | Reserved; must be zero. | Reserved; must be zero.

Other resources that you can access over the network, including printer queues, communication-device queues, and pipes, are audited in the same manner as files.

When auditing of write events is enabled, auditing logs the event the first time the file is opened with write permission. File size changes (including truncation) are audited by bits 5 and 9.

acc1_count
Specifies a SHORT variable that indicates the number of access_list structures that follow the access_info_1 structure.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Access Functions, access_list, NetAccessEnum, NetAccessGetInfo, NetAccessSetInfo


access_list

Windows 95/98/Me: The access_list structure defines the resource permissions for individual users and groups.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000.

struct _access_list {
  char       acl_ugname[LM20_UNLEN+1];
  char       acl_ugname_pad_1;
  short      acl_access;
};

Members

acl_ugname
Specifies a string that contains a username or a groupname. The constant LM20_UNLEN specifies the maximum number of characters in the name.
acl_ugname_pad_1
Specifies padding inserted to align the next member.
acl_access
Describes the permissions associated with the username or groupname. This member can be a combination of the following values.
Value | Meaning
ACCESS_READ | Permission to read data from a resource and, by default, to execute the resource.
ACCESS_WRITE | Permission to write data to the resource.
ACCESS_CREATE | Permission to create an instance of the resource (such as a file); data can be written to the resource when the resource is created.
ACCESS_EXEC | Permission to execute the resource.
ACCESS_DELETE | Permission to delete the resource.
ACCESS_ATRIB | Permission to modify the resource's attributes (such as the date and time when a file was last modified).
ACCESS_PERM | Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user or application.
ACCESS_ALL | Permission to read, write, create, execute, and delete resources, and to modify their attributes and permissions.
ACCESS_GROUP | Permission for a particular group; this value indicates that the entry is for a group.
ACCESS_NONE | The user does not have access to the resource.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Access Functions, access_info_1, NetAccessEnum, NetAccessGetInfo, NetAccessSetInfo


ADMIN_OTHER_INFO

The ADMIN_OTHER_INFO structure contains error message information. The NetAlertRaise and NetAlertRaiseEx functions use the ADMIN_OTHER_INFO structure to specify information when raising an administrator's interrupting message.

typedef struct _ADMIN_OTHER_INFO {
  DWORD  alrtad_errcode;
  DWORD  alrtad_numstrings;
}ADMIN_OTHER_INFO, *PADMIN_OTHER_INFO, *LPADMIN_OTHER_INFO;

Members

alrtad_errcode
Specifies the error code for the new message written to the message log.
alrtad_numstrings
Specifies the number (0-9) of consecutive Unicode strings written to the message log.

Remarks

Variable-length data follows the ADMIN_OTHER_INFO structure in the alert message buffer if you specify one or more strings in the alrtad_numstrings member. The calling application must allocate and free the memory for all structures and variable-length data in an alert message buffer.

See NetAlertRaise and NetAlertRaiseEx for code samples that demonstrate how to raise an administrative alert.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Alert Functions, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, STD_ALERT, USER_OTHER_INFO, NetAlertRaise, NetAlertRaiseEx


AT_ENUM

The AT_ENUM structure contains information about a sumbitted job. The NetScheduleJobEnum function uses this structure to enumerate and return information about an entire queue of submitted jobs.

typedef struct _AT_ENUM {
  DWORD       JobId;
  DWORD_PTR   JobTime;
  DWORD       DaysOfMonth;
  UCHAR       DaysOfWeek;
  UCHAR       Flags;
  LPWSTR      Command;
} AT_ENUM, *PAT_ENUM, *LPAT_ENUM;

Members

JobId
Specifies a DWORD value that contains the job identifier of a submitted (queued) job.
JobTime
Specifies a value that indicates the time of day at which the job is scheduled to run. The time is the local time at a computer on which the schedule service is running; it is measured from midnight, and is expressed in milliseconds.
DaysOfMonth
Specifies a DWORD value that contains a set of bit flags representing the days of the month. For each bit that is set, the scheduled job will run at the time specified by the JobTime member, on the corresponding day of the month. Bit 0 corresponds to the first day of the month, and so on.

The value of the bitmask is zero if the job was scheduled to run only once, at the first occurrence of JobTime.

DaysOfWeek
Specifies a variable that contains a set of bit flags representing the days of the week. For each bit that is set, the scheduled job will run at the time specified by the JobTime member, on the corresponding day of the week. Bit 0 corresponds to Monday, and so on.

The value of the bitmask is zero if the job was scheduled to run only once, at the first occurrence of JobTime.

Flags
Specifies a variable that contains a set of bit flags describing job properties. This member can be one or more of the following values.
Value | Meaning
JOB_RUN_PERIODICALLY | This flag is equal to its original value, that is, the value when the job was submitted.
JOB_EXEC_ERROR | If this flag is set, it indicates that the schedule service failed to successfully execute the job the last time it was scheduled to run.
JOB_RUNS_TODAY | If this flag is set, it indicates that the job is scheduled to execute on the current day; the value of the JobTime member is greater than the current time of day at the computer where the job is queued.
JOB_NONINTERACTIVE | This flag is equal to its original value, that is, the value when the job was submitted.

Command
Pointer to a Unicode string that contains the name of the command, batch program, or binary file to execute.

Remarks

For more information about setting the bit flags to schedule jobs that execute once, jobs that execute multiple times, and jobs that execute periodically without deletion, see NetScheduleJobAdd.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmat.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Schedule Functions, NetScheduleJobEnum


AT_INFO

The AT_INFO structure contains information about a job. The NetScheduleJobAdd function uses the structure to specify information when scheduling a job. The NetScheduleJobGetInfo function uses the structure to retrieve information about a job that has already been submitted.

typedef struct _AT_INFO {
  DWORD_PTR   JobTime;
  DWORD       DaysOfMonth;
  UCHAR       DaysOfWeek;
  UCHAR       Flags;
  LPWSTR      Command;
} AT_INFO, *PAT_INFO, *LPAT_INFO;

Members

JobTime
Specifies a value that indicates the time of day at which the job is scheduled to run. The time is the local time at a computer on which the schedule service is running; it is measured from midnight, and is expressed in milliseconds.
DaysOfMonth
Specifies a DWORD value that contains a set of bit flags representing the days of the month. For each bit that is set, the scheduled job will run at the time specified by the JobTime member, on the corresponding day of the month. Bit 0 corresponds to the first day of the month, and so on.

The value of the bitmask is zero if the job was scheduled to run only once, at the first occurrence of JobTime.

DaysOfWeek
Specifies a variable that contains a set of bit flags representing the days of the week. For each bit that is set, the scheduled job will run at the time specified by the JobTime member, on the corresponding day of the week. Bit 0 corresponds to Monday, and so on.

The value of the bitmask is zero if the job was scheduled to run only once, at the first occurrence of JobTime.

Flags
Specifies a variable that contains a set of bit flags describing job properties.

Submitting jobs. When you submit a job using a call to the NetScheduleJobAdd function, you can specify one of the following values.
Value Meaning
JOB_RUN_PERIODICALLY If you set this flag, the job runs, and continues to run, on each day for which a corresponding bit is set in the DaysOfMonth or DaysOfWeek member. The job is not deleted after it executes.

If this flag is clear, the job runs only once for each bit set in these members. The job is deleted after it executes once.
JOB_ADD_CURRENT_DATE If you set this flag, the job executes at the first occurrence of JobTime at the computer where the job is queued.

Setting this flag is equivalent to setting the bit for the current day in the DaysOfMonth member.
JOB_NONINTERACTIVE If you set this flag, the job does not run interactively.

If this flag is clear, the job runs interactively.

Retrieving job information. When you call NetScheduleJobGetInfo to retrieve job information, the function can return one or more of the following values.
Value | Meaning
JOB_RUN_PERIODICALLY | This flag is equal to its original value, that is, the value when the job was submitted.
JOB_EXEC_ERROR | If this flag is set, it indicates that the schedule service failed to successfully execute the job the last time it was scheduled to run.
JOB_RUNS_TODAY | If this flag is set, it indicates that the job is scheduled to execute on the current day; the value of the JobTime member is greater than the current time of day at the computer where the job is queued.
JOB_NONINTERACTIVE | This flag bit is equal to its original value, that is, the value when the job was submitted.

Command
Pointer to a Unicode string that contains the name of the command, batch program, or binary file to execute.

Remarks

For more information about scheduling jobs that execute once, jobs that execute multiple times, and jobs that execute periodically without deletion, see NetScheduleJobAdd.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmat.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Schedule Functions, NetScheduleJobAdd, NetScheduleJobGetInfo


CONNECTION_INFO_0

The CONNECTION_INFO_0 structure contains the identification number of a connection.

typedef struct _CONNECTION_INFO_0 {
  DWORD    coni0_id;
} CONNECTION_INFO_0, *PCONNECTION_INFO_0, *LPCONNECTION_INFO_0;

Members

coni0_id
Specifies a connection identification number.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetConnectionEnum


CONNECTION_INFO_1

The CONNECTION_INFO_1 structure contains the identification number of a connection, number of open files, connection time, number of users on the connection, and the type of connection.

typedef struct _CONNECTION_INFO_1 {
  DWORD     coni1_id;
  DWORD     coni1_type;
  DWORD     coni1_num_opens;
  DWORD     coni1_num_users;
  DWORD     coni1_time;
  LPWSTR    coni1_username;
  LPWSTR    coni1_netname;
} CONNECTION_INFO_1, *PCONNECTION_INFO_1, *LPCONNECTION_INFO_1;

Members

coni1_id
Specifies a connection identification number.
coni1_type
Specifies the type of connection made from the local device name to the shared resource. This member can be one of the following values.
Value | Meaning
STYPE_DISKTREE | Print queue
STYPE_PRINTQ | Disk drive
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)

coni1_num_opens
Specifies the number of files currently open as a result of the connection.
coni1_num_users
Specifies the number of users on the connection.
coni1_time
Specifies the number of seconds that the connection has been established.
coni1_username
Pointer to a Unicode string. If the server sharing the resource is running with user-level security, the coni1_username member describes which user made the connection. If the server is running with share-level security, coni1_username describes which computer (computername) made the connection.
coni1_netname
Pointer to a Unicode string specifying either the share name of the server's shared resource or the computername of the client. The value of this member depends on which name was specified as the qualifier parameter to the NetConnectionEnum function. The name not specified in the qualifier parameter to NetConnectionEnum is automatically supplied to coni1_netname.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetConnectionEnum


connection_info_50

Windows 95/98/Me: The connection_info_50 structure contains the connection type, number of open files, connection time, and the number of users on the connection.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the CONNECTION_INFO_1 structure instead.

struct _connection_info_50 {
  unsigned short  coni50_type;
  unsigned short  coni50_num_opens;
  unsigned long   coni50_time;
  char FAR *      coni50_netname;
  char FAR *      coni50_username;
};

Members

coni50_type
Specifies an unsigned SHORT variable that indicates the type of connection made from the local device to the shared resource. This member can be one of the following share types.
Value | Meaning
STYPE_DISKTREE | Print queue
STYPE_PRINTQ | Disk drive
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)

coni50_num_opens
Specifies an unsigned SHORT variable that indicates the number of files currently open as a result of the connection.
coni50_time
Specifies an unsigned LONG variable that indicates the length of the established connection, in seconds.
coni50_netname
Pointer to a string specifying either the share name of the server's shared resource or the computername of the client. The value of this member depends on which name was specified as the pszQualifier parameter to the NetConnectionEnum function. The name not specified in the pszQualifier parameter to NetConnectionEnum is automatically supplied to coni50_netname.
coni50_username
Pointer to a string. If the server sharing the resource is running with user-level security, the coni50_username member describes which user made the connection. If the server is running with share-level security, coni50_username describes which computer (computername) made the connection.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetConnectionEnum


DFS_INFO_1

The DFS_INFO_1 structure contains the name of a Distributed File System (Dfs) link in a named Dfs root.

typedef struct _DFS_INFO_1 {
    LPWSTR  EntryPath;
} DFS_INFO_1, *PDFS_INFO_1, *LPDFS_INFO_1;

Members

EntryPath
Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link. The string can be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

Remarks

The Dfs functions use the DFS_INFO_1 structure to retrieve information about a Dfs link.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, NetDfsEnum, NetDfsGetInfo, NetDfsGetClientInfo


DFS_INFO_2

The DFS_INFO_2 structure contains information about a Distributed File System (Dfs) link in a named Dfs root. The information includes Dfs name, status, and the number of Dfs paths associated with the link.

typedef struct _DFS_INFO_2 {
  LPWSTR  EntryPath;
  LPWSTR  Comment;
  DWORD   State;
  DWORD   NumberOfStorages;
} DFS_INFO_2, *PDFS_INFO_2, *LPDFS_INFO_2;

Members

EntryPath
Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link in a named Dfs root. The string can be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

Comment
Pointer to a null-terminated Unicode character string that contains a comment associated with the Dfs link.
State
Specifies a set of bit flags that describe the status of the Dfs link. This member must be one of the following values.
Value | Meaning
DFS_VOLUME_STATE_OK | The specified Dfs link is in the normal state.
DFS_VOLUME_STATE_INCONSISTENT | The internal Dfs database is inconsistent with the specified Dfs link. Attempts to repair the inconsistency have failed.
DFS_VOLUME_STATE_OFFLINE | The specified Dfs link is offline or unavailable.
DFS_VOLUME_STATE_ONLINE | The specified Dfs link is available.

NumberOfStorages
Specifies the number of root shares (Dfs paths) associated with the Dfs link.

Remarks

The Dfs functions use the DFS_INFO_2 structure to retrieve information about a Dfs link.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, NetDfsEnum, NetDfsGetInfo, NetDfsGetClientInfo


DFS_INFO_3

The DFS_INFO_3 structure contains detailed information about a Distributed File System (Dfs) link in a named Dfs root. The information includes Dfs name, status, and each Dfs path associated with the link.

typedef struct _DFS_INFO_3 {
  LPWSTR  EntryPath;
  LPWSTR  Comment;
  DWORD   State;
  DWORD   NumberOfStorages;
  LPDFS_STORAGE_INFO Storage;
} DFS_INFO_3, *PDFS_INFO_3, *LPDFS_INFO_3;

Members

EntryPath
Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link in a named Dfs root. The string can be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

Comment
Pointer to a null-terminated Unicode character string that contains a comment associated with the Dfs link.
State
Specifies a set of bit flags that describe the status of the Dfs link. This member must be one of the following values.
Value | Meaning
DFS_VOLUME_STATE_OK | The specified Dfs link is in the normal state.
DFS_VOLUME_STATE_INCONSISTENT | The internal Dfs database is inconsistent with the specified Dfs link. Attempts to repair the inconsistency have failed.
DFS_VOLUME_STATE_OFFLINE | The specified Dfs link is offline or unavailable.
DFS_VOLUME_STATE_ONLINE | The specified Dfs link is available.

NumberOfStorages
Specifies the number of root shares (Dfs paths) associated with the Dfs link.
Storage
Pointer to an array of DFS_STORAGE_INFO structures. The NumberOfStorages member specifies the number of structures in the array.

Remarks

A DFS_INFO_3 structure contains one or more DFS_STORAGE_INFO structures, one for each Dfs path specified for the Dfs link.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, DFS_STORAGE_INFO, NetDfsEnum, NetDfsGetInfo, NetDfsGetClientInfo


DFS_INFO_4

The DFS_INFO_4 structure contains detailed information about a Distributed File System (Dfs) link in a named Dfs root. The information includes Dfs name, status, GUID, time-out, and each Dfs path associated with the link.

Note This structure is currently being evaluated and may or may not be supported in future versions.

typedef struct _DFS_INFO_4 {
  LPWSTR  EntryPath;
  LPWSTR  Comment;
  DWORD   State;
  ULONG   Timeout;
  GUID    Guid;
  DWORD   NumberOfStorages;
  LPDFS_STORAGE_INFO Storage;
} DFS_INFO_4, *PDFS_INFO_4, *LPDFS_INFO_4;

Members

EntryPath
Pointer to a null-terminated Unicode character string that specifies the Universal Naming Convention path of a Dfs link in a named Dfs root. The string can be in one of two forms. The first form is as follows:
\\Dfsname\sharename\path_to_link

where Dfsname is the name of a Windows NT/Windows 2000 server that hosts the root of a stand-alone Dfs implementation; sharename is the name of a share published on the Dfs host server; and path_to_link specifies the path on the physical share.

The second form is as follows:

\\DomainName\DomDfsname\path_to_link

where DomainName is the name of a Windows NT/Windows 2000 domain that hosts the Dfs root; DomDfsname is the name of the root of a domain-based Dfs implementation published in the domain's directory service; and path_to_link specifies the path on the physical share.

Windows 95/98/Me: The DomDfsname must be identical to the name of the share that hosts the root of the domain-based Dfs.

Comment
Pointer to a null-terminated Unicode character string that contains a comment associated with the Dfs link.
State
Specifies a set of bit flags that describe the status of the Dfs link. This member is one of the following values.
Value | Meaning
DFS_VOLUME_STATE_OK | The specified Dfs link is in the normal state.
DFS_VOLUME_STATE_INCONSISTENT | The internal Dfs database is inconsistent with the specified Dfs link. Attempts to repair the inconsistency have failed.
DFS_VOLUME_STATE_OFFLINE | The specified Dfs link is offline or unavailable.
DFS_VOLUME_STATE_ONLINE | The specified Dfs link is available.

Timeout
Specifies the time-out, in seconds, of the Dfs link.
Guid
Specifies the GUID of the Dfs link.
NumberOfStorages
Specifies the number of root shares (Dfs paths) associated with the Dfs link.
Storage
Pointer to an array of DFS_STORAGE_INFO structures. The NumberOfStorages member specifies the number of structures in the array.

Remarks

A DFS_INFO_4 structure contains one or more DFS_STORAGE_INFO structures, one for each Dfs path specified for the Dfs link.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, NetDfsEnum, NetDfsGetClientInfo, NetDfsGetInfo, DFS_STORAGE_INFO


DFS_INFO_100

The DFS_INFO_100 structure contains a comment associated with a Distributed File System (Dfs) link in a named Dfs root.

typedef struct _DFS_INFO_100 {
  LPWSTR  Comment;
} DFS_INFO_100, *PDFS_INFO_100, *LPDFS_INFO_100;

Members

Comment
Pointer to a null-terminated Unicode character string that contains the comment associated with the specified Dfs link.

Remarks

The Dfs functions use the DFS_INFO_100 structure to retrieve information about a Dfs link.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, NetDfsGetInfo, NetDfsSetInfo


DFS_INFO_101

The DFS_INFO_101 structure contains a storage state to associate with a Distributed File System (Dfs) link in a named Dfs root.

Note This structure is currently being evaluated and may or may not be supported in future versions.

typedef struct _DFS_INFO_101 {
  DWORD  State;
} DFS_INFO_101, *PDFS_INFO_101, *LPDFS_INFO_101;

Members

State
Specifies a set of bit flags that describe the status of the storage server. Following are valid values for this member. Note that the DFS_STORAGE_STATE_OFFLINE and DFS_STORAGE_STATE_ONLINE values are mutually exclusive.
Value | Meaning
DFS_STORAGE_STATE_OFFLINE | The specified computer is to be marked offline or unavailable.
DFS_STORAGE_STATE_ONLINE | The specified computer is to be marked online or available.
DFS_STORAGE_STATE_ACTIVE | The specified computer is to be made the active machine. This value is optional.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, NetDfsSetClientInfo, NetDfsSetInfo


DFS_INFO_102

The DFS_INFO_102 structure contains a time-out to associate with a Distributed File System (Dfs) link in a named Dfs root.

Note This structure is currently being evaluated and may or may not be supported in future versions.

typedef struct _DFS_INFO_102 {
  ULONG   Timeout;
} DFS_INFO_102, *PDFS_INFO_102, *LPDFS_INFO_102;

Members

Timeout
Specifies the time-out, in seconds, to apply to the specified Dfs link.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, NetDfsSetClientInfo, NetDfsSetInfo


DFS_INFO_200

The DFS_INFO_200 structure contains the name associated with a domain-based Distributed File System (Dfs) root.

Note This structure is currently being evaluated and may or may not be supported in future versions.

typedef struct _DFS_INFO_200 {
  LPWSTR  FtDfsName;
} DFS_INFO_200, *PDFS_INFO_200, *LPDFS_INFO_200;

Members

FtDfsName
Pointer to a null-terminated Unicode character string that contains the domain-based Dfs name.

Remarks

The Dfs functions use the DFS_INFO_200 structure to enumerate all the domain-based Dfs roots in a domain.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, NetDfsEnum


DFS_STORAGE_INFO

The DFS_STORAGE_INFO structure contains the status of a share referenced by a Distributed File System (Dfs) link in a named Dfs root.

typedef struct _DFS_STORAGE_INFO {
  ULONG   State;
  LPWSTR  ServerName;
  LPWSTR  ShareName;
} DFS_STORAGE_INFO, *PDFS_STORAGE_INFO, *LPDFS_STORAGE_INFO;

Members

State
Specifies a set of bit flags that describe the status of the host server. Following are valid values for this member. Note that the DFS_STORAGE_STATE_OFFLINE and DFS_STORAGE_STATE_ONLINE values are mutually exclusive.
Value | Meaning
DFS_STORAGE_STATE_OFFLINE | The specified computer is offline or unavailable.
DFS_STORAGE_STATE_ONLINE | The specified computer is available.
DFS_STORAGE_STATE_ACTIVE | The specified computer is to be made the active machine. This value is optional.

ServerName
Pointer to a null-terminated Unicode character string that specifies the name of the host server that the Dfs link references.
ShareName
Pointer to a null-terminated Unicode character string that specifies the name of the share on the host server that the Dfs link references.

Remarks

A DFS_INFO_3 structure contains one or more DFS_STORAGE_INFO structures, one for each Dfs path specified for the Dfs link.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmdfs.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Distributed File System (Dfs) Functions, DFS_INFO_3, NetDfsEnum, NetDfsGetInfo


ERRLOG_OTHER_INFO

The ERRLOG_OTHER_INFO structure contains error log information. The NetAlertRaise and NetAlertRaiseEx functions use the ERRLOG_OTHER_INFO structure to specify information when adding a new entry to the error log.

type struct _ERRLOG_OTHER_INFO {
  DWORD  alrter_errcode;
  DWORD  alrter_offset;
}ERRLOG_OTHER_INFO, *PERRLOG_OTHER_INFO, *LPERRLOG_OTHER_INFO;

Members

alrter_errcode
Specifies the error code that was written to the error log.
alrter_offset
Specifies the offset for the new entry in the error log.

Remarks

The calling application must allocate and free the memory for all structures and variable-length data in an alert message buffer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Alert Functions, ADMIN_OTHER_INFO, PRINT_OTHER_INFO, STD_ALERT, USER_OTHER_INFO, NetAlertRaise, NetAlertRaiseEx


FILE_INFO_2

The FILE_INFO_2 structure contains the identification number for a file, device, or pipe.

typedef struct _FILE_INFO_2 {
  DWORD    fi2_id;
} FILE_INFO_2, *PFILE_INFO_2, *LPFILE_INFO_2;

Members

fi2_id
Specifies a DWORD value that contains the identification number assigned to the resource when it is opened.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, NetFile Functions, NetFileEnum, NetFileGetInfo, FILE_INFO_3


FILE_INFO_3

The FILE_INFO_3 structure contains the identification number and other pertinent information about files, devices, and pipes.

typedef struct _FILE_INFO_3 {
  DWORD     fi3_id;
  DWORD     fi3_permissions;
  DWORD     fi3_num_locks;
  LPWSTR    fi3_pathname;
  LPWSTR    fi3_username;
} FILE_INFO_3, *PFILE_INFO_3, *LPFILE_INFO_3;

Members

fi3_id
Specifies a DWORD value that contains the identification number assigned to the resource when it is opened.
fi3_permissions
Specifies a DWORD value that contains the access permissions associated with the opening application. This member can be one or more of the following values.
Value | Meaning
PERM_FILE_READ | Permission to read a resource and, by default, execute the resource.
PERM_FILE_WRITE | Permission to write to a resource.
PERM_FILE_CREATE | Permission to create a resource; data can be written when creating the resource.

fi3_num_locks
Specifies a DWORD value that contains the number of file locks on the file, device, or pipe.
fi3_pathname
Pointer to a Unicode string that specifies the path of the opened resource.
fi3_username
Pointer to a Unicode string that specifies which user (on servers that have user-level security) or which computer (on servers that have share-level security) opened the resource.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, NetFile Functions, NetFileEnum, NetFileGetInfo, FILE_INFO_2


file_info_50

Windows 95/98/Me: The file_info_50 structure contains information about a shared resource.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the FILE_INFO_3 structure instead.

struct _file_info_50 {
  unsigned long   fi50_id;
  unsigned short  fi50_permissions;
  unsigned short  fi50_num_locks;
  char FAR *      fi50_pathname;
  char FAR *      fi50_username;
  char FAR *      fi50_sharename;
};

Members

fi50_id
Specifies the identification number assigned to the resource when it is opened.
fi50_permissions
Specifies the access permissions associated with the opening application. This member can be a combination of the following values.
Value | Meaning
PERM_FILE_READ | Permission to read a resource and, by default, execute the resource.
PERM_FILE_WRITE | Permission to write to a resource.
PERM_FILE_CREATE | Permission to create a resource; data can be written when creating the resource.

fi50_num_locks
Specifies the number of locks on the resource.
fi50_pathname
Pointer to a string that contains the path of the opened resource.
fi50_username
Pointer to a string that specifies which user opened the resource.
fi50_sharename
Pointer to a string that specifies the share name associated with the open resource.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, NetFile Functions, NetFileEnum


GROUP_INFO_0

The GROUP_INFO_0 structure contains the name of a global group in the security database.

typedef struct _GROUP_INFO_0 {
  LPWSTR   grpi0_name;
}GROUP_INFO_0, *PGROUP_INFO_0, *LPGROUP_INFO_0;

Members

grpi0_name
Pointer to a null-terminated Unicode character string that specifies the name of the global group. The constant GNLEN specifies the maximum number of characters in the string.

When you call the NetGroupSetInfo function this member specifies the new name of the global group.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Group Functions, NetGroupAdd, NetGroupEnum, NetGroupGetInfo, NetGroupSetInfo


GROUP_INFO_1

The GROUP_INFO_1 structure contains a global group name and a comment to associate with the group.

typedef struct _GROUP_INFO_1 {
  LPWSTR   grpi1_name;
  LPWSTR   grpi1_comment;
}GROUP_INFO_1, *PGROUP_INFO_1, *LPGROUP_INFO_1;

Members

grpi1_name
Pointer to a null-terminated Unicode character string that specifies the name of the global group. The constant GNLEN specifies the maximum number of characters in the string.

When you call the NetGroupSetInfo function this member is ignored.

grpi1_comment
Pointer to a null-terminated Unicode character string that specifies a remark associated with the global group. This member can be a null string. The comment can contain MAXCOMMENTSZ characters.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Group Functions, NetGroupAdd, NetGroupEnum, NetGroupGetInfo, NetGroupSetInfo


GROUP_INFO_2

The GROUP_INFO_2 structure contains information about a global group, including name, identifier, and resource attributes.

Whistler: On Whistler and later, it is recommended that you use the GROUP_INFO_3 structure instead.

typedef struct _GROUP_INFO_2 {
  LPWSTR   grpi2_name;
  LPWSTR   grpi2_comment;
  DWORD    grpi2_group_id;
  DWORD    grpi2_attributes;
}GROUP_INFO_2, *PGROUP_INFO_2;

Members

grpi2_name
Pointer to a null-terminated Unicode character string that specifies the name of the global group. The constant GNLEN specifies the maximum number of characters in the string.

When you call the NetGroupSetInfo function this member is ignored.

grpi2_comment
Pointer to a null-terminated Unicode character string that contains a remark associated with the global group. This member can be a null string. The comment can contain MAXCOMMENTSZ characters.
grpi2_group_id
Specifies a DWORD value that contains the relative identifier of the global group. The NetUserAdd and NetUserSetInfo functions ignore this member.
grpi2_attributes
Specifies a DWORD value that contains the attributes of a group.

Windows NT/2000 or later: On Windows NT 4.0 and Windows 2000, you can no longer set these attributes. They are hard-coded to SE_GROUP_MANDATORY, SE_GROUP_ENABLED, and SE_GROUP_ENABLED_BY_DEFAULT. For more information, see TOKEN_GROUPS.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Group Functions, NetGroupAdd, NetGroupEnum, NetGroupGetInfo, NetGroupSetInfo, TOKEN_GROUPS


GROUP_INFO_3

[This is preliminary documentation and subject to change.]

The GROUP_INFO_3 structure contains information about a global group, including name, security identifier (SID), and resource attributes.

Whistler: Note that the GROUP_INFO_3 structure supersedes the GROUP_INFO_2 structure. It is recommended that you use GROUP_INFO_3 instead of the GROUP_INFO_2 structure.

typedef struct _GROUP_INFO_3{
  LPWSTR   grpi3_name;
  LPWSTR   grpi3_comment;
  PSID     grpi3_group_sid;
  DWORD    grpi3_attributes;
}GROUP_INFO_3, *PGROUP_INFO_3;

Members

grpi3_name
Pointer to a null-terminated Unicode character string that specifies the name of the global group. The constant GNLEN specifies the maximum number of characters in the string.

When you call the NetGroupSetInfo function this member is ignored.

grpi3_comment
Pointer to a null-terminated Unicode character string that contains a remark associated with the global group. This member can be a null string. The comment can contain MAXCOMMENTSZ characters.
grpi3_group_sid
Pointer to a SID structure that contains the security identifier (SID) that uniquely identifies the global group. The NetUserAdd and NetUserSetInfo functions ignore this member.
grpi3_attributes
Specifies a DWORD value that contains the attributes of a group.

Windows NT/2000 or later: On Windows NT 4.0 and Windows 2000, you can no longer set these attributes. They are hard-coded to SE_GROUP_MANDATORY, SE_GROUP_ENABLED, and SE_GROUP_ENABLED_BY_DEFAULT. For more information, see TOKEN_GROUPS.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Group Functions, NetGroupAdd, NetGroupEnum, NetGroupGetInfo, NetGroupSetInfo, TOKEN_GROUPS, SID


GROUP_INFO_1002

The GROUP_INFO_1002 structure contains a comment to associate with a global group.

typedef struct _GROUP_INFO_1002 {
  LPWSTR  grpi1002_comment;
} GROUP_INFO_1002, *PGROUP_INFO_1002, *LPGROUP_INFO_1002;

Members

grpi1002_comment
Pointer to a null-terminated Unicode character string that contains a remark to associate with the global group. This member can be a null string. The comment can contain MAXCOMMENTSZ characters.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Group Functions, NetGroupSetInfo


GROUP_INFO_1005

The GROUP_INFO_1005 structure contains the resource attributes associated with a global group.

typedef struct _GROUP_INFO_1005 {
  DWORD  grpi1005_attributes;
} GROUP_INFO_1005, *PGROUP_INFO_1005, *LPGROUP_INFO_1005;

Members

grpi1005_attributes
Specifies the attributes of a global group.

Windows NT/2000 or later: On Windows NT 4.0 and Windows 2000, you can no longer set these attributes. They are hard-coded to SE_GROUP_MANDATORY, SE_GROUP_ENABLED, and SE_GROUP_ENABLED_BY_DEFAULT. For more information, see TOKEN_GROUPS.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Group Functions, NetGroupSetInfo, TOKEN_GROUPS


GROUP_USERS_INFO_0

The GROUP_USERS_INFO_0 structure contains global group member information.

typedef struct _GROUP_USERS_INFO_0 {
  LPWSTR  grui0_name;
} GROUP_USERS_INFO_0, *PGROUP_USERS_INFO_0, *LPGROUP_USERS_INFO_0;

Members

grui0_name
Pointer to a null-terminated Unicode character string that specifies a name. The constant UNLEN specifies the maximum number of characters in the name. For more information, see the following Remarks section.

Remarks

If you are calling the NetGroupGetUsers function or the NetGroupSetUsers function, the grui0_name member contains the name of a user that is a member of the specified group.

If you are calling the NetUserGetGroups function or the NetUserSetGroups function, the grui0_name member contains the name of a global group to which the specified user belongs.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Group Functions, NetGroupGetUsers, NetGroupSetUsers, NetUserGetGroups, NetUserGetInfo, NetUserSetGroups


GROUP_USERS_INFO_1

The GROUP_USERS_INFO_1 structure is obsolete on Windows NT 4.0 and Windows 2000. Global group member information is available at the GROUP_USERS_INFO_0 level.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Group Functions


LOCALGROUP_INFO_0

The LOCALGROUP_INFO_0 structure contains a local group name.

typedef struct _LOCALGROUP_INFO_0 {
  LPWSTR   lgrpi0_name;
}LOCALGROUP_INFO_0, *PLOCALGROUP_INFO_0, *LPLOCALGROUP_INFO_0;

Members

lgrpi0_name
Pointer to a Unicode string that specifies a local group name. The constant GNLEN specifies the maximum number of characters in the string.

When you call the NetLocalGroupAdd function, this member specifies the name of a new local group. When you call the NetLocalGroupSetInfo function, this member specifies the new name of an existing local group.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Local Group Functions, NetLocalGroupAdd, NetLocalGroupEnum, NetLocalGroupSetInfo


LOCALGROUP_INFO_1

The LOCALGROUP_INFO_1 structure contains a local group name and a comment describing the local group.

typedef struct _LOCALGROUP_INFO_1 {
  LPWSTR   lgrpi1_name;
  LPWSTR   lgrpi1_comment;
}LOCALGROUP_INFO_1, *PLOCALGROUP_INFO_1, *LPLOCALGROUP_INFO_1;

Members

lgrpi1_name
Pointer to a Unicode string that specifies a local group name. The constant GNLEN specifies the maximum number of characters in the string.

This member is ignored when you call the NetLocalGroupSetInfo function.

lgrpi1_comment
Pointer to a Unicode string that contains a remark associated with the local group. This member can be a null string. The comment can have as many as MAXCOMMENTSZ characters.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Local Group Functions, NetLocalGroupAdd, NetLocalGroupEnum, NetLocalGroupGetInfo, NetLocalGroupSetInfo


LOCALGROUP_INFO_1002

The LOCALGROUP_INFO_1002 structure contains a comment describing a local group.

typedef struct _LOCALGROUP_INFO_1002 {
  LPWSTR  lgrpi1002_comment;
}LOCALGROUP_INFO_1002, *PLOCALGROUP_INFO_1002, *LPLOCALGROUP_INFO_1002;

Members

lgrpi1002_comment
Pointer to a Unicode string that specifies a remark associated with the local group. This member can be a null string. The comment can have as many as MAXCOMMENTSZ characters.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Local Group Functions, NetLocalGroupSetInfo


LOCALGROUP_MEMBERS_INFO_0

The LOCALGROUP_MEMBERS_INFO_0 structure contains the security identifier (SID) associated with a local group member. The member can be a user account or a global group account.

typedef struct _LOCALGROUP_MEMBERS_INFO_0 {
  PSID  lgrmi0_sid;
} LOCALGROUP_MEMBERS_INFO_0;

Members

lgrmi0_sid
Pointer to the security identifier of the local group member.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Local Group Functions, LOCALGROUP_MEMBERS_INFO_1,
LOCALGROUP_MEMBERS_INFO_2,
LOCALGROUP_MEMBERS_INFO_3, NetLocalGroupAddMembers, NetLocalGroupDelMembers, NetLocalGroupGetMembers, NetLocalGroupSetMembers


LOCALGROUP_MEMBERS_INFO_1

The LOCALGROUP_MEMBERS_INFO_1 structure contains the security identifier (SID) and account information associated with the member of a local group.

typedef struct _LOCALGROUP_MEMBERS_INFO_1 {
  PSID         lgrmi1_sid;
  SID_NAME_USE lgrmi1_sidusage;
  LPWSTR       lgrmi1_name;
} LOCALGROUP_MEMBERS_INFO_1, *PLOCALGROUP_MEMBERS_INFO_1, *LPLOCALGROUP_MEMBERS_INFO_1;

Members

lgrmi1_sid
Pointer to the security identifier of an account that is a member of this local group member. The account can be a user account or a global group account.
lgrmi1_sidusage
Specifies the account type associated with the security identifier specified in the lgrmi1_sid member. The following values are valid.
Value | Meaning
SidTypeUser | The account is a user account.
SidTypeGroup | The account is a global group account.
SidTypeWellKnownGroup | The account is a well-known group account (such as Everyone).
SidTypeDeletedAccount | The account has been deleted.
SidTypeUnknown | The account type cannot be determined.

lgrmi1_name
Pointer to the account name of the local group member identified by lgrmi1_sid. The lgrmi1_name member does not include the domain name.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Local Group Functions, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_2, LOCALGROUP_MEMBERS_INFO_3,
NetLocalGroupGetMembers


LOCALGROUP_MEMBERS_INFO_2

The LOCALGROUP_MEMBERS_INFO_2 structure contains the security identifier (SID) and account information associated with a local group member.

typedef struct _LOCALGROUP_MEMBERS_INFO_2 {
  PSID         lgrmi2_sid;
  SID_NAME_USE lgrmi2_sidusage;
  LPWSTR       lgrmi2_domainandname;
} LOCALGROUP_MEMBERS_INFO_2, *PLOCALGROUP_MEMBERS_INFO_2, *LPLOCALGROUP_MEMBERS_INFO_2;

Members

lgrmi2_sid
Pointer to the security identifier of a local group member. The local group member can be a user account or a global group account.
lgrmi2_sidusage
Specifies the account type associated with the security identifier specified in the lgrmi2_sid member. The following values are valid.
Value | Meaning
SidTypeUser | The account is a user account.
SidTypeGroup | The account is a global group account.
SidTypeWellKnownGroup | The account is a well-known group account (such as Everyone).
SidTypeDeletedAccount | The account has been deleted.
SidTypeUnknown | The account type cannot be determined.

lgrmi2_domainandname
Pointer to the account name of the local group member identified by lgrmi2_sid. The lgrmi2_domainandname member includes the domain name and has the form:
<DomainName>\<AccountName>

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Local Group Functions, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_1, LOCALGROUP_MEMBERS_INFO_3,
NetLocalGroupGetMembers


LOCALGROUP_MEMBERS_INFO_3

The LOCALGROUP_MEMBERS_INFO_3 structure contains the account name and domain name associated with a local group member.

typedef struct _LOCALGROUP_MEMBERS_INFO_3 {
  LPWSTR  lgrmi3_domainandname;
} LOCALGROUP_MEMBERS_INFO_3;

Members

lgrmi3_domainandname
Pointer to a null-terminated Unicode string specifying the account name of the local group member prefixed by the domain name and the "\" separator character. For example:
<DomainName>\<AccountName>

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Local Group Functions, LOCALGROUP_MEMBERS_INFO_0, LOCALGROUP_MEMBERS_INFO_1, LOCALGROUP_MEMBERS_INFO_2,
NetLocalGroupAddMembers, NetLocalGroupDelMembers, NetLocalGroupGetMembers, NetLocalGroupSetMembers


LOCALGROUP_USERS_INFO_0

The LOCALGROUP_USERS_INFO_0 structure contains local group member information.

typedef struct _LOCALGROUP_USERS_INFO_0 {
  LPWSTR  lgrui0_name;
} LOCALGROUP_USERS_INFO_0, *PLOCALGROUP_USERS_INFO_0,
  *LPLOCALGROUP_USERS_INFO_0;

Members

lgrui0_name
Pointer to a Unicode string specifying the name of a local group to which the user belongs.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Local Group Functions, NetUserGetLocalGroups


MSG_INFO_0

The MSG_INFO_0 structure specifies a message alias.

typedef struct _MSG_INFO_0 {
  LPWSTR  msgi0_name;
}MSG_INFO_0, *PMSG_INFO_0, *LPMSG_INFO_0;

Members

msgi0_name
Pointer to a Unicode string that specifies the alias to which the message is to be sent. The constant LEN specifies the maximum number of characters in the string.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmmsg.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Message Functions, NetMessageNameEnum, NetMessageNameGetInfo


MSG_INFO_1

The MSG_INFO_1 structure specifies a message alias. This structure exists only for compatibility. Message forwarding is not supported.

typedef struct _MSG_INFO_1 {
  LPWSTR  msgi1_name;
  DWORD   msgi1_forward_flag;
  LPWSTR  msgi1_forward;
}MSG_INFO_1, *PMSG_INFO_1, *LPMSG_INFO_1;

Members

msgi1_name
Pointer to a Unicode string that specifies the alias to which the message is to be sent. The constant LEN specifies the maximum number of characters in the string.
msgi1_forward_flag
This member must be zero.
msgi1_forward
This member must be NULL.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmmsg.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Message Functions, NetMessageNameEnum, NetMessageNameGetInfo


NET_DISPLAY_GROUP

The NET_DISPLAY_GROUP structure contains information that an account manager can access to determine information about group accounts.

typedef struct _NET_DISPLAY_GROUP {
  LPWSTR   grpi3_name;
  LPWSTR   grpi3_comment;
  DWORD    grpi3_group_id;
  DWORD    grpi3_attributes;
  DWORD    grpi3_next_index;
} NET_DISPLAY_GROUP, *PNET_DISPLAY_GROUP;

Members

grpi3_name
Pointer to a Unicode string that specifies the name of the group.
grpi3_comment
Pointer to a Unicode string that contains a comment associated with the group. This string can be a null string, or it can have any number of characters before the terminating null character.
grpi3_group_id
Specifies a DWORD value that contains the relative identifier of the group. The relative identifier is determined by the accounts database when the group is created. It uniquely identifies the group to the account manager within the domain. The NetUserAdd and NetUserSetInfo functions ignore this member.
grpi3_attributes
Lists the attributes of the defined group.

Windows NT/2000 or later: On Windows NT 4.0 and Windows 2000, you can no longer set these attributes. They are hard-coded to SE_GROUP_MANDATORY, SE_GROUP_ENABLED, and SE_GROUP_ENABLED_BY_DEFAULT. For more information, see TOKEN_GROUPS.

grpi3_next_index
Specifies the index of the last entry returned by the NetQueryDisplayInformation function. Pass this value as the Index parameter to NetQueryDisplayInformation to return the next logical entry. Note that you should not use the value of this member for any purpose except to retrieve more data with additional calls to NetQueryDisplayInformation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Get Functions, NetUserAdd, NetUserSetInfo, NetQueryDisplayInformation, TOKEN_GROUPS


NET_DISPLAY_MACHINE

The NET_DISPLAY_MACHINE structure contains information that an account manager can access to determine information about computers and their attributes.

typedef struct _NET_DISPLAY_MACHINE {
  LPWSTR   usri2_name;
  LPWSTR   usri2_comment;
  DWORD    usri2_flags;
  DWORD    usri2_user_id;
  DWORD    usri2_next_index;
} NET_DISPLAY_MACHINE, *PNET_DISPLAY_MACHINE;

Members

usri2_name
Pointer to a Unicode string that specifies the name of the machine to access.
usri2_comment
Pointer to a Unicode string that contains a comment associated with the computer. This string can be a null string, or it can have any number of characters before the terminating null character.
usri2_flags
Specifies a DWORD value which contains values that determine several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 and Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. Windows NT/Windows 2000 ignores this value.
UF_PASSWRD_NOTREQD | No password is required.
UF_PASSWRD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out (blocked). For the NetUserSetInfo function, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWORD | Windows NT/2000 or later: Represents the password, which will never expire on the account.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Windows 2000 or later: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or a Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri2_user_id
Specifies the relative identifier of the machine. The relative identifier is determined by the accounts database when the machine is defined.
usri2_next_index
Specifies the index of the last entry returned by the NetQueryDisplayInformation function. Pass this value as the Index parameter to NetQueryDisplayInformation to return the next logical entry. Note that you should not use the value of this member for any purpose except to retrieve more data with additional calls to NetQueryDisplayInformation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Get Functions, NetUserAdd, NetUserSetInfo, NetQueryDisplayInformation


NET_DISPLAY_USER

The NET_DISPLAY_USER structure contains information that an account manager can access to determine information about user accounts.

typedef struct _NET_DISPLAY_USER {
  LPWSTR   usri1_name;
  LPWSTR   usri1_comment;
  DWORD    usri1_flags;
  LPWSTR   usri1_full_name;
  DWORD    usri1_user_id;
  DWORD    usri1_next_index;
} NET_DISPLAY_USER, *PNET_DISPLAY_USER;

Members

usri1_name
Pointer to a Unicode string that specifies the name of the user account.
usri1_comment
Pointer to a Unicode string that contains a comment associated with the user. This string can be a null string, or it can have any number of characters before the terminating null character (MAXCOMMENTSZ).
usri1_flags
Specifies a DWORD value which contains values that determine several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 and Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. Windows NT/Windows 2000 ignores this value.
UF_PASSWRD_NOTREQD | No password is required.
UF_PASSWRD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out (blocked). For the NetUserSetInfo function, this value can be cleared to unlock a previously locked account. This value cannot be used to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWORD | Windows NT/2000 or later: Represents the password, which will never expire on the account.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Windows 2000 or later: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or a Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri1_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri1_user_id
Specifies the relative identifier of the user. The relative identifier is determined by the accounts database when the user is created. It uniquely defines this user account to the account manager within the domain.
usri1_next_index
Specifies the index of the last entry returned by the NetQueryDisplayInformation function. Pass this value as the Index parameter to NetQueryDisplayInformation to return the next logical entry. Note that you should not use the value of this member for any purpose except to retrieve more data with additional calls to NetQueryDisplayInformation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Get Functions, NetUserAdd, NetUserSetInfo, NetQueryDisplayInformation


PRINT_OTHER_INFO

The PRINT_OTHER_INFO structure contains information about a print job. The NetAlertRaise and NetAlertRaiseEx functions use the PRINT_OTHER_INFO structure to specify information when a job has finished printing, or when a printer needs intervention.

typedef struct _PRINT_OTHER_INFO {
  DWORD  alrtpr_jobid;
  DWORD  alrtpr_status;
  DWORD  alrtpr_submitted;
  DWORD  alrtpr_size;
}PRINT_OTHER_INFO, *PPRINT_OTHER_INFO, *LPPRINT_OTHER_INFO;

Members

alrtpr_jobid
Specifies the identification number of the print job.
alrtpr_status
Specifies a bit mask describing the status of the print job.

You can obtain the overall status of the job by checking PRJOB_QSTATUS (bits 0 and 1). The following values are possible.
Value | Meaning
PRJOB_QS_QUEUED | The print job is in the queue waiting to be scheduled.
PRJOB_QS_PAUSED | The print job is in the queue, but it has been paused. (When a job is paused, it cannot be scheduled.)
PRJOB_QS_SPOOLING | The print job is in the process of being spooled.
PRJOB_QS_PRINTING | The job is currently printing.

If the print job is in the PRJOB_QS_PRINTING state, you can check bits 2 through 8 for the device's status (PRJOB_DEVSTATUS). Bit 15 is also meaningful.
Value | Meaning | Bit
PRJOB_COMPLETE | The job has completed printing. | 2
PRJOB_INTERV | The destination printer requires an operator's intervention. | 3
PRJOB_ERROR | There is an error at the destination printer. | 4
PRJOB_DESTOFFLINE | The destination printer is offline. | 5
PRJOB_DESTPAUSED | The destination printer is paused. | 6
PRJOB_NOTIFY | A printing alert should be raised. | 7
PRJOB_DESTNOPAPER | The destination printer is out of paper. | 8
PRJOB_DELETED | The printing job is being deleted. | 15

alrtpr_submitted
Specifies the time at which the print job was submitted. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT.
alrtpr_size
Specifies the size, in bytes, of the print job.

Remarks

Additional variable-length data follows the PRINT_OTHER_INFO structure in the alert message buffer. The information is in the form of contiguous null-terminated character strings, as follows.

String | Meaning
computername | The computer that submitted the print job.
username | The user who submitted the print job.
queuename | The print queue to which the job was submitted.
destination | The printer destination (device) to which the print job was routed.
status | The status of the print job.

The calling application must allocate and free the memory for all structures and variable-length data in an alert message buffer.

See NetAlertRaiseEx for a code sample that demonstrates how to raise a print alert.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Alert Functions, ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, STD_ALERT, USER_OTHER_INFO, NetAlertRaise, NetAlertRaiseEx


REPL_EDIR_INFO_0

The REPL_EDIR_INFO_0 structure contains the name of a subdirectory in the main export directory.

typedef struct _REPL_EDIR_INFO_0 {
  LPWSTR         rped0_dirname;
} REPL_EDIR_INFO_0, *PREPL_EDIR_INFO_0, *LPREPL_EDIR_INFO_0;

Members

rped0_dirname
Specifies the name of a subdirectory in the main export directory.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplExportDirEnum, NetReplExportDirGetInfo


REPL_EDIR_INFO_1

The REPL_EDIR_INFO_1 structure contains the name of a subdirectory in the main export directory and the values of the subdirectory's replication controls.

typedef struct _REPL_EDIR_INFO_1 {
  LPWSTR         rped1_dirname;
  DWORD          rped1_integrity;
  DWORD          rped1_extent;
} REPL_EDIR_INFO_1, *PREPL_EDIR_INFO_1, *LPREPL_EDIR_INFO_1;

Members

rped1_dirname
Specifies the name of a particular subdirectory in the main export directory.
rped1_integrity
Specifies one of the following wait-until-stabilized options for the importer. (The integrity replication control determines when a master updates a client.)
Value | Meaning
REPL_INTEGRITY_TREE | When the importer detects a change to the replicated tree, it copies the entire tree to a temporary top-level directory and renames the original tree in the original directory. If any problem occurs while copying the tree, the importer deletes the temporary directory. This action guarantees the integrity of the entire tree.
REPL_INTEGRITY_FILE | When an importer detects mismatched file attributes in the tree structure (such as date, time, name, or size), it copies the file to a temporary local file and renames the local file in place of the existing file. This action guarantees only the integrity of individual files, not of the entire tree.

rped1_extent
Specifies one of the following flags to determine the selection of files for replication within the main export directory.
Value | Meaning
REPL_EXTENT_FILE | Selects a single file in the main export directory.
REPL_EXTENT_TREE | Selects the entire subtree in the main export directory. If you clear a top-level directory in the Control panel (Control Panel -> Server -> Replicator -> Manage Export), only the files in that top-level directory will be replicated; subdirectories or their contents will not be replicated.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplExportDirAdd, NetReplExportDirEnum, NetReplExportDirGetInfo, NetReplExportDirSetInfo


REPL_EDIR_INFO_2

The REPL_EDIR_INFO_2 structure contains the name of a subdirectory in the main export directory, the values of the subdirectory's replication controls, and lock status data.

typedef struct _REPL_EDIR_INFO_2 {
  LPWSTR         rped2_dirname;
  DWORD          rped2_integrity;
  DWORD          rped2_extent;
  DWORD          rped2_lockcount;
  DWORD          rped2_locktime;
} REPL_EDIR_INFO_2, *PREPL_EDIR_INFO_2, *LPREPL_EDIR_INFO_2;

Members

rped2_dirname
Specifies the name of a particular subdirectory in the main export directory.
rped2_integrity
Specifies one of the following wait-until-stabilized options for the importer. (The integrity replication control determines when a master updates a client.)
Value | Meaning
REPL_INTEGRITY_TREE | When the importer detects a change to the replicated tree, it copies the entire tree to a temporary top-level directory and renames the original tree in the original directory. If any problem occurs while copying the tree, the importer deletes the temporary directory. This action guarantees the integrity of the entire tree.
REPL_INTEGRITY_FILE | When an importer detects mismatched file attributes in the tree structure (such as date, time, name, or size), it copies the file to a temporary local file and renames the local file in place of the existing file. This action guarantees only the integrity of individual files, not of the entire tree.

rped2_extent
Specifies one of the following flags to determine the selection of files for replication within the main export directory.
Value | Meaning
REPL_EXTENT_FILE | Selects a single file in the main export directory.
REPL_EXTENT_TREE | Selects the entire subtree in the main export directory. If you clear a top-level directory in the Control panel (Control Panel -> Server -> Replicator -> Manage Export), only the files in that top-level directory will be replicated; subdirectories or their contents will not be replicated.

rped2_lockcount
Specifies the current lock count (the number of outstanding locks) on the subdirectory. This member can be modified only with a call to the NetReplExportDirLock function or the NetReplExportDirUnlock function.
rped2_locktime
This member specifies, in seconds, the time at which the directory was locked since 1970. The locktime member indicates the time (in seconds since 00:00:00, January 1, 1970, GMT) when the directory was first locked, or is 0 if the directory is not locked at the present time.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplExportDirLock, NetReplExportDirUnlock


REPL_EDIR_INFO_1000

The REPL_EDIR_INFO_1000 structure contains the value of the integrity replication control.

typedef struct _REPL_EDIR_INFO_1000 {
  DWORD          rped1000_integrity;
} REPL_EDIR_INFO_1000, *PREPL_EDIR_INFO_1000, *LPREPL_EDIR_INFO_1000;

Members

rped1000_integrity
Specifies one of the following wait-until-stabilized options for the importer. (The integrity replication control determines when a master updates a client.)
Value | Meaning
REPL_INTEGRITY_TREE | When the importer detects a change to the replicated tree, it copies the entire tree to a temporary top-level directory and renames the original tree in the existing directory. If any problem occurs while copying the tree, the importer deletes the temporary directory. This action guarantees the integrity of the entire tree.
REPL_INTEGRITY_FILE | When an importer detects mismatched file attributes in the tree structure (such as date, time, name, or size), it copies the file to a temporary local file and renames the local file in place of the existing file. This action guarantees only the integrity of individual files, not of the entire tree.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplExportDirSetInfo


REPL_EDIR_INFO_1001

The REPL_EDIR_INFO_1001 structure contains the value of the extent replication control.

typedef struct _REPL_EDIR_INFO_1001 {
  DWORD          rped1001_extent;
} REPL_EDIR_INFO_1001, *PREPL_EDIR_INFO_1001, *LPREPL_EDIR_INFO_1001;

Members

rped1001_extent
Specifies one of the following flags to determine the selection of files for replication within the main export directory.
Value | Meaning
REPL_EXTENT_FILE | Selects a single file in the main export directory.
REPL_EXTENT_TREE | Selects the entire subtree in the main export directory. If you clear a top-level directory in the Control panel (Control Panel -> Server -> Replicator -> Manage Export), only the files in that top-level directory will be replicated; subdirectories or their contents will not be replicated.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplExportDirSetInfo


REPL_IDIR_INFO_0

The REPL_IDIR_INFO_0 structure contains the name of a subdirectory in the main import directory.

typedef struct _REPL_IDIR_INFO_0 {
  LPWSTR         rpid0_dirname;
} REPL_IDIR_INFO_0, *PREPL_IDIR_INFO_0, *LPREPL_IDIR_INFO_0;

Members

rpid0_dirname
Specifies the name of a subdirectory in the main import directory.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplImportDirAdd, NetReplImportDirEnum, NetReplImportDirGetInfo


REPL_IDIR_INFO_1

The REPL_IDIR_INFO_1 structure contains specifies subdirectories and synchronizing states in the main import directory of the replicator.

typedef struct _REPL_IDIR_INFO_1 {
  LPWSTR         rpid1_dirname;
  DWORD          rpid1_state;
  LPWSTR         rpid1_mastername;
  DWORD          rpid1_last_update_time;
  DWORD          rpid1_lockcount;
  DWORD          rpid1_locktime;
} REPL_IDIR_INFO_1, *PREPL_IDIR_INFO_1, *LPREPL_IDIR_INFO_1;

Members

rpid1_dirname
Specifies the name of a subdirectory in the main import directory.
rpid1_state
Specifies a DWORD value that contains a set of bit flags indicating the synchronization state of the import subdirectory. This member can be one of the following values.
Value | Meaning
REPL_STATE_OK | The directory currently has a master and is receiving regular update notices from it.
REPL_STATE_NO_MASTER | The directory is not supported by any master and is typically empty.
REPL_STATE_NO_SYNC | The directory has a master, but the master has not sent update notices within the specified time period. (The rp0_interval member specifies the time period.) For more information, see the following Remarks section.
REPL_STATE_NEVER_REPLICATED | The file replicator service has not been started on the import server.

rpid1_mastername
Specifies the name of the exporter for the selected subdirectory. If the rpid1_state member is equal to REPL_STATE_NEVER_REPLICATED, this member is a NULL string.
rpid1_last_update_time
Specifies the time, in seconds since 00:00:00, January 1, 1970, GMT, when the selected directory was last updated. If the rpid1_state member is equal to REPL_STATE_NEVER_REPLICATED, this member is equal to 0.
rpid1_lockcount
Specifies the current lock count on the subdirectory. You can modify this member only with the NetReplImportDirLock and NetReplImportDirUnlock functions.
rpid1_locktime
Specifies the time at which the directory was locked, in seconds, since 00:00:00, January 1, 1970, GMT.

Remarks

When a master does not send updates, and the rpid1_state member is equal to REPL_STATE_NO_SYNC, it can be due to various reasons. These reasons include communication failure, the master crashing, a locked directory, open files on the import server at update time, or an unstable directory on the master.

To retrieve the interval (rp0_interval) that elapses between the times the exporter should contact each import server for changes, you can call the NetReplGetInfo function and specify information level REPL_INFO_0.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplImportDirEnum, NetReplImportDirGetInfo, NetReplImportDirLock, NetReplImportDirUnlock


REPL_INFO_0

The REPL_INFO_0 structure contains configuration information for the file replicator service, including import and export paths and other replication parameters.

typedef struct _REPL_INFO_0 {
  DWORD          rp0_role;
  LPWSTR         rp0_exportpath;
  LPWSTR         rp0_exportlist;
  LPWSTR         rp0_importpath;
  LPWSTR         rp0_importlist;
  LPWSTR         rp0_logonusername;
  DWORD          rp0_interval;
  DWORD          rp0_pulse;
  DWORD          rp0_guardtime;
  DWORD          rp0_random;
} REPL_INFO_0, *PREPL_INFO_0, *LPREPL_INFO_0;

Members

rp0_role
Specifies either one or both of the following values.
Value | Meaning
REPL_ROLE_EXPORT | Exports directory control information.
REPL_ROLE_IMPORT | Imports directory control information on a Windows NT/Windows 2000 workstation.

rp0_exportpath
Specifies the root directory that holds the exportpath parameter.
rp0_exportlist
Specifies the list of computers or domains to export, using semicolon delimiters. If the list is empty, the function uses the local domain.
rp0_importpath
Specifies the root directory that holds the importpath parameter. If both the export tree and import tree are on an NTFS partition, the file replicator service copies the file permissions as well as the files themselves.
rp0_importlist
Specifies the list of computers or domains to import, using semicolon delimiters. If the list is empty, the function uses the local domain.
rp0_logonusername
Specifies the account the file replicator service attempts to use if the user is not logged on.
rp0_interval
Specifies the interval, in minutes, that elapses between the times the exporter contacts each import server for changes in each top-level directory.

The exporter sends a sync message if it detects a change to the directory since the last contact, or a pulse message if it detects no change. The default setting is 5 minutes.

rp0_pulse
Specifies a multiplier for synchronization of the importer and exporter. The default setting is 2.

If the exporter fails to respond to an importer after the number of minutes obtained by multiplying rp0_pulse times rp0_interval, the importer sends a message to the exporter asking for an update. If the exporter fails to respond again (after the same amount of time) the importer reports that the top-level directory is not synchronized. If the exporter fails to respond a third time, the importer no longer notifies the exporter.

The importer resumes notifying the exporter when the exporter responds and replication is successful.

rp0_guardtime
Specifies the period of time, in minutes (by default), that each file and directory within the replicated directory must be stable before the file replicator service sends a synchronizing message with an updated checksum.

This setting is valid only for top-level directories when the wait-until-stabilized feature is enabled. The value of rp0_guardtime cannot be more than rp0_interval divided by 2.

rp0_random
Specifies the maximum time, in seconds, that import servers wait before requesting an update from the exporter. The default value is 60. You may want to increase this value substantially if you increase rp0_interval to 60 or more minutes. The maximum value is 120.

Import servers generate a random number of seconds, from 0 to the value of rp0_random. After receiving an update notice from the exporter, the import server waits the generated amount of seconds before requesting the replica from the export server. This can prevent the export server from being overloaded with simultaneous update requests.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplGetInfo, NetReplSetInfo


REPL_INFO_1000

The REPL_INFO_1000 structure contains the time interval that the exporter uses to access the import server and check for changes in each top-level directory.

typedef struct _REPL_INFO_1000 {
  DWORD          rp1000_interval;
} REPL_INFO_1000, *PREPL_INFO_1000, *LPREPL_INFO_1000;

Members

rp1000_interval
Specifies the interval, in minutes, that elapses between the times the exporter contacts each import server for changes in each top-level directory.

The exporter sends a sync message if it detects a change to the directory since the last contact, or a pulse message if it detects no change. The default setting is 5 minutes.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplSetInfo


REPL_INFO_1001

The REPL_INFO_1001 structure contains a count that the file replicator service uses to synchronize the importer to the exporter.

typedef struct _REPL_INFO_1001 {
  DWORD          rp1001_pulse;
} REPL_INFO_1001, *PREPL_INFO_1001, *LPREPL_INFO_1001;

Members

rp1001_pulse
Specifies a multiplier for synchronization of the importer and exporter. The default setting is 2.

If the exporter fails to respond to an importer after the number of minutes obtained by multiplying rp1001_pulse times rpX_interval, the importer sends a message to the exporter asking for an update. If the exporter fails to respond again (after the same amount of time), the importer reports that the top-level directory is not synchronized. If the exporter fails to respond a third time, the importer no longer notifies the exporter.

The importer resumes notifying the exporter when the exporter responds and replication is successful.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplSetInfo


REPL_INFO_1002

The REPL_INFO_1002 structure contains the period of time that each file and directory within the replicated directory must be stable before the file replicator service updates the client. This value is valid only for top-level directories when the wait-until-stabilized feature is enabled.

typedef struct _REPL_INFO_1002 {
  DWORD          rp1002_guardtime;
} REPL_INFO_1002, *PREPL_INFO_1002, *LPREPL_INFO_1002;

Members

rp1002_guardtime
Specifies the period of time, in minutes (by default), that each file and directory within the replicated directory must be stable before the file replicator service sends a synchronizing message with an updated checksum.

This setting is valid only for top-level directories when the wait-until-stabilized feature is enabled. The value of rp1002_guardtime cannot be more than rpX_interval divided by 2.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplSetInfo


REPL_INFO_1003

The REPL_INFO_1003 structure contains the period of time that import servers wait before requesting a replica from the export server.

typedef struct _REPL_INFO_1003 {
  DWORD          rp1003_random;
} REPL_INFO_1003, *PREPL_INFO_1003, *LPREPL_INFO_1003;

Members

rp1003_random
Specifies the maximum period of time, in seconds, that import servers wait before requesting an update from the exporter. The default value is 60. You may want to increase this value substantially if you increase rpX_interval to 60 or more minutes. The maximum value is 120.

Import servers generate a random number of seconds, from 0 to the value of rpX_random. After receiving an update notice from the exporter, the import server waits the generated amount of seconds before requesting the replica from the export server. This can prevent the export server from being overloaded with simultaneous update requests.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or earlier.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmrepl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Replicator Functions, NetReplSetInfo


security_info_1

Windows 95/98/Me: The security_info_1 structure contains information about a server's security level.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000.

struct _security_info_1 {
  unsigned long  sec1_security;
  char FAR *     sec1_container;
  char FAR *     sec1_ab_server;
  char FAR *     sec1_ab_dll;
};

Members

sec1_security
Specifies an unsigned long variable that indicates the security level on the specified server. This member can be one of the following values.
Value | Meaning
SEC_SECURITY_SHARE | Share-level security
SEC_SECURITY_WINNT | User-level security (Windows NT workstation)
SEC_SECURITY_WINNTAS | User-level security (Windows NT domain)
SEC_SECURITY_NETWARE | User-level security (NetWare 3.x)

sec1_container
Pointer to a string that specifies the domain.
sec1_ab_server
Pointer to a string that specifies the address book server.
sec1_ab_dll
Pointer to a string that specifies the DLL name of the address book provider.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, NetSecurityGetInfo


server_info_1

Windows 95/98/Me: The server_info_1 structure contains information about the specified server, including its name, type, and networking software version.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the SERVER_INFO_101 structure instead.

struct _server_info_1 {
  char             sv1_name[CNLEN + 1];
  unsigned char    sv1_version_major;
  unsigned char    sv1_version_minor;
  unsigned long    sv1_type;
  char FAR *       sv1_comment;
};

Members

sv1_name
Pointer to a string specifying the name of the server of interest.
sv1_version_major
Specifies the major release version number of the networking software the server is running.
sv1_version_minor
Specifies the minor release version number of the networking software the server is running.
sv1_type
Specifies the type of networking software the computer is running. This member can be one of the following values.
Value | Meaning
SV_TYPE_WORKSTATION | A LAN Manager workstation
SV_TYPE_SERVER | A LAN Manager server
SV_TYPE_SQLSERVER | Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL | Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL | Backup domain controller
SV_TYPE_TIME_SOURCE | Server running the Timesource service
SV_TYPE_AFP | Apple File Protocol server
SV_TYPE_NOVELL | Novell server
SV_TYPE_DOMAIN_MEMBER | LAN Manager 2.x domain member
SV_TYPE_PRINTQ_SERVER | Server sharing print queue
SV_TYPE_DIALIN_SERVER | Server running dial-in service
SV_TYPE_ALL | All servers

sv1_comment
Pointer to a string containing a comment that describes the server. This member can be null.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, server_info_50, NetServerGetInfo


server_info_50

Windows 95/98/Me: The server_info_50 structure contains information about the specified server, including the name, type, and networking software version.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000.

struct _server_info_50 {
  char             sv50_name[CNLEN + 1];
  unsigned char    sv50_version_major;
  unsigned char    sv50_version_minor;
  unsigned long    sv50_type;
  char FAR *       sv50_comment;
  unsigned short   sv50_security;
  unsigned short   sv50_auditing;
  char FAR *       sv50_container;
  char FAR *       sv50_ab_server;
  char FAR *       sv50_ab_dll;
};

Members

sv50_name
Pointer to a string specifying the name of the server of interest.
sv50_version_major
Specifies the major release version number of the networking software the server is running.
sv50_version_minor
Specifies the minor release version number of the networking software the server is running.
sv50_type
Specifies the type of networking software the server is running. This member can be one of the following values.
Value | Meaning
SV_TYPE_WORKSTATION | A LAN Manager workstation
SV_TYPE_SERVER | A LAN Manager server
SV_TYPE_SQLSERVER | Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL | Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL | Backup domain controller
SV_TYPE_TIME_SOURCE | Server running the Timesource service
SV_TYPE_AFP | Apple File Protocol server
SV_TYPE_NOVELL | Novell server
SV_TYPE_DOMAIN_MEMBER | LAN Manager 2.x domain member
SV_TYPE_PRINTQ_SERVER | Server sharing print queue
SV_TYPE_DIALIN_SERVER | Server running dial-in service
SV_TYPE_ALL | All servers

sv50_comment
Pointer to a string containing a comment that describes the server. This member can be null.
sv50_security
Specifies the security type of the server. This member can be one of the following values.
Value | Meaning
SV_SECURITY_SHARE | Share-level security
SV_SECURITY_WINNT | User-level security (Windows NT workstation)
SV_SECURITY_WINNTAS | User-level security (Windows NT domain)
SV_SECURITY_NETWARE | User-level security (NetWare 3.x)

sv50_auditing
Specifies a variable that indicates whether auditing is enabled on the server. If this member is zero, auditing is disabled. If this member is any other value, auditing is enabled.
sv50_container
Pointer to a string that specifies the security server or domain.
sv50_ab_server
Pointer to a string that specifies the address book server.
sv50_ab_dll
Pointer to a string that specifies the name of the address book service provider DLL.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, server_info_1, NetServerGetInfo


SERVER_INFO_100

The SERVER_INFO_100 structure contains information about the specified server, including the name and platform.

typedef struct _SERVER_INFO_100 {
  DWORD     sv100_platform_id;
  LPWSTR    sv100_name;
} SERVER_INFO_100, *PSERVER_INFO_100, *LPSERVER_INFO_100;

Members

sv100_platform_id
Specifies the information level to use for platform-specific information. This member can be one of the following values, defined in the lmcons.h file: PLATFORM_ID_DOS, PLATFORM_ID_OS2, PLATFORM_ID_NT, PLATFORM_ID_OSF, or PLATFORM_ID_VMS.
sv100_name
Pointer to a Unicode string specifying the name of a server.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerDiskEnum, NetServerEnum, NetServerGetInfo


SERVER_INFO_101

The SERVER_INFO_101 structure contains information about the specified server, including name, platform, type of server, and associated software.

typedef struct _SERVER_INFO_101 {
  DWORD     sv101_platform_id;
  LPWSTR    sv101_name;
  DWORD     sv101_version_major;
  DWORD     sv101_version_minor;
  DWORD     sv101_type;
  LPWSTR    sv101_comment;
} SERVER_INFO_101, *PSERVER_INFO_101, *LPSERVER_INFO_101;

Members

sv101_platform_id
Specifies the information level to use for platform-specific information. This member can be one of the following values, defined in the lmcons.h file: PLATFORM_ID_DOS, PLATFORM_ID_OS2, PLATFORM_ID_NT, PLATFORM_ID_OSF, or PLATFORM_ID_VMS.
sv101_name
Pointer to a Unicode string specifying the name of a server.
sv101_version_major
Specifies, in the least significant 4 bits of the byte, the major release version number of the operating system. The most significant 4 bits of the byte specifies the server type. The mask MAJOR_VERSION_MASK should be used to ensure correct results.
sv101_version_minor
Specifies the minor release version number of the operating system.
sv101_type
Specifies the type of software the computer is running. This member can be one of the following values.
Value | Meaning
SV_TYPE_WORKSTATION | A LAN Manager workstation
SV_TYPE_SERVER | A LAN Manager server
SV_TYPE_SQLSERVER | Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL | Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL | Backup domain controller
SV_TYPE_TIME_SOURCE | Server running the Timesource service
SV_TYPE_AFP | Apple File Protocol server
SV_TYPE_NOVELL | Novell server
SV_TYPE_DOMAIN_MEMBER | LAN Manager 2.x domain member
SV_TYPE_LOCAL_LIST_ONLY | Servers maintained by the browser
SV_TYPE_PRINTQ_SERVER | Server sharing print queue
SV_TYPE_DIALIN_SERVER | Server running dial-in service
SV_TYPE_XENIX_SERVER | Xenix server
SV_TYPE_SERVER_MFPN | Microsoft File and Print for NetWare
SV_TYPE_NT | Windows NT/Windows 2000 workstation or server
SV_TYPE_WFW | Server running Windows for Workgroups
SV_TYPE_SERVER_NT | Windows NT/Windows 2000 server that is not a domain controller
SV_TYPE_POTENTIAL_BROWSER | Server that can run the browser service
SV_TYPE_BACKUP_BROWSER | Server running a browser service as backup
SV_TYPE_MASTER_BROWSER | Server running the master browser service
SV_TYPE_DOMAIN_MASTER | Server running the domain master browser
SV_TYPE_DOMAIN_ENUM | Primary domain
SV_TYPE_WINDOWS | Windows 95 or later
SV_TYPE_ALL | All servers
SV_TYPE_TERMINALSERVER | Terminal Server
SV_TYPE_CLUSTER_NT | Server clusters available in the domain
SV_TYPE_CLUSTER_VS_NT | Whistler: Cluster virtual servers available in the domain

sv101_comment
Pointer to a Unicode string specifying a comment describing the server. The comment can be null.

Remarks

To retrieve a value that indicates whether a share is the root volume in a Dfs tree structure, you must call the NetShareGetInfo function and specify information level 1005.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerEnum, NetServerGetInfo, NetServerSetInfo, NetShareGetInfo


SERVER_INFO_102

The SERVER_INFO_102 structure contains information about the specified server, including name, platform, type of server, attributes, and associated software.

typedef struct _SERVER_INFO_102 {
  DWORD     sv102_platform_id;
  LPWSTR    sv102_name;
  DWORD     sv102_version_major;
  DWORD     sv102_version_minor;
  DWORD     sv102_type;
  LPWSTR    sv102_comment;
  DWORD     sv102_users;
  LONG      sv102_disc;
  BOOL      sv102_hidden;
  DWORD     sv102_announce;
  DWORD     sv102_anndelta;
  DWORD     sv102_licenses;
  LPWSTR    sv102_userpath;
} SERVER_INFO_102, *PSERVER_INFO_102, *LPSERVER_INFO_102;

Members

sv102_platform_id
Specifies the information level to use for platform-specific information. This member can be one of the following values, defined in the lmcons.h file: PLATFORM_ID_DOS, PLATFORM_ID_OS2, PLATFORM_ID_NT, PLATFORM_ID_OSF, or PLATFORM_ID_VMS.
sv102_name
Pointer to a Unicode string specifying the name of a server.
sv102_version_major
Specifies, in the least significant 4 bits, the major release version number of the operating system. The most significant 4 bits specifies the server type. The mask MAJOR_VERSION_MASK should be used to ensure correct results.
sv102_version_minor
Specifies the minor release version number of the operating system.
sv102_type
Specifies the type of software the computer is running. This member can be one of the following values.
Value | Meaning
SV_TYPE_WORKSTATION | A LAN Manager workstation
SV_TYPE_SERVER | A LAN Manager server
SV_TYPE_SQLSERVER | Any server running with Microsoft SQL Server
SV_TYPE_DOMAIN_CTRL | Primary domain controller
SV_TYPE_DOMAIN_BAKCTRL | Backup domain controller
SV_TYPE_TIME_SOURCE | Server running the Timesource service
SV_TYPE_AFP | Apple File Protocol server
SV_TYPE_NOVELL | Novell server
SV_TYPE_DOMAIN_MEMBER | LAN Manager 2.x domain member
SV_TYPE_LOCAL_LIST_ONLY | Servers maintained by the browser
SV_TYPE_PRINTQ_SERVER | Server sharing print queue
SV_TYPE_DIALIN_SERVER | Server running dial-in service
SV_TYPE_XENIX_SERVER | Xenix server
SV_TYPE_SERVER_MFPN | Microsoft File and Print for NetWare
SV_TYPE_NT | Windows NT/Windows 2000 workstation or server
SV_TYPE_WFW | Server running Windows for Workgroups
SV_TYPE_SERVER_NT | Windows NT/Windows 2000 server that is not a domain controller
SV_TYPE_POTENTIAL_BROWSER | Server that can run the browser service
SV_TYPE_BACKUP_BROWSER | Server running a browser service as backup
SV_TYPE_MASTER_BROWSER | Server running the master browser service
SV_TYPE_DOMAIN_MASTER | Server running the domain master browser
SV_TYPE_DOMAIN_ENUM | Primary domain
SV_TYPE_WINDOWS | Windows 95 or later
SV_TYPE_ALL | All servers
SV_TYPE_TERMINALSERVER | Terminal Server
SV_TYPE_CLUSTER_NT | Server clusters available in the domain
SV_TYPE_CLUSTER_VS_NT | Whistler: Cluster virtual servers available in the domain

sv102_comment
Pointer to a Unicode string specifying a comment describing the server. The comment can be null.
sv102_users
Specifies the number of users who can attempt to log on to the system server. Note that it is the license server that determines how many of these users can actually log on.
sv102_disc
Specifies the auto-disconnect time, in minutes. A session is disconnected if it is idle longer than the period of time specified by the sv102_disc member. If the value of sv102_disc is SV_NODISC, auto-disconnect is not enabled.
sv102_hidden
Specifies whether the server is visible to other computers in the same network domain. This member can be one of the following values.
Value | Meaning
SV_VISIBLE | Server is visible.
SV_HIDDEN | Server is not visible.

sv102_announce
Specifies the network announce rate, in seconds. This rate determines how often the server is announced to other computers on the network. For more information about how much the announce rate can vary from the period of time specified by this member, see SERVER_INFO_1018.
sv102_anndelta
Specifies the delta value for the announce rate, in milliseconds. This value specifies how much the announce rate can vary from the period of time specified in the sv102_announce member.

The delta value allows randomly varied announce rates. For example, if the sv102_announce member has the value 10 and the sv102_anndelta member has the value 1, the announce rate can vary from 9.999 seconds to 10.001 seconds.

sv102_licenses
Specifies the number of users per license. By default, this number is SV_USERS_PER_LICENSE.
sv102_userpath
Pointer to a Unicode string specifying the path to user directories.

Remarks

To retrieve a value that indicates whether a share is the root volume in a Dfs tree structure, you must call the NetShareGetInfo function and specify information level 1005.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo, NetServerSetInfo, NetShareGetInfo, SERVER_INFO_1018


SERVER_INFO_402

The SERVER_INFO_402 structure contains information about a specified server.

typedef struct _SERVER_INFO_402 {
  DWORD          sv402_ulist_mtime;
  DWORD          sv402_glist_mtime;
  DWORD          sv402_alist_mtime;
  LPWSTR         sv402_alerts;
  DWORD          sv402_security;
  DWORD          sv402_numadmin;
  DWORD          sv402_lanmask;
  LPWSTR         sv402_guestacct;
  DWORD          sv402_chdevs;
  DWORD          sv402_chdevq;
  DWORD          sv402_chdevjobs;
  DWORD          sv402_connections;
  DWORD          sv402_shares;
  DWORD          sv402_openfiles;
  DWORD          sv402_sessopens;
  DWORD          sv402_sessvcs;
  DWORD          sv402_sessreqs;
  DWORD          sv402_opensearch;
  DWORD          sv402_activelocks;
  DWORD          sv402_numreqbuf;
  DWORD          sv402_sizreqbuf;
  DWORD          sv402_numbigbuf;
  DWORD          sv402_numfiletasks;
  DWORD          sv402_alertsched;
  DWORD          sv402_erroralert;
  DWORD          sv402_logonalert;
  DWORD          sv402_accessalert;
  DWORD          sv402_diskalert;
  DWORD          sv402_netioalert;
  DWORD          sv402_maxauditsz;
  LPWSTR         sv402_srvheuristics;
} SERVER_INFO_402, *PSERVER_INFO_402, *LPSERVER_INFO_402;

Members

sv402_ulist_mtime
Specifies the last time the user list was modified. The value is expressed as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT, and applies to servers running with user-level security.
sv402_glist_mtime
Specifies the last time the group list was modified. The value is expressed as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT, and applies to servers running with user-level security.
sv402_alist_mtime
Specifies the last time the access control list was modified. The value is expressed as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT, and applies to servers running with user-level security.
sv402_alerts
Pointer to a Unicode string specifying the list of user names on the server. Spaces separate the names.
sv402_security
Specifies the security type of the server. This member can be one of the following values.
Value | Meaning
SV_SHARESECURITY | Share-level security
SV_USERSECURITY | User-level security

sv402_numadmin
Specifies how many administrators the server can accommodate at one time.
sv402_lanmask
Specifies the order in which the network device drivers are served.
sv402_guestacct
Pointer to a Unicode string specifying the name of a reserved account for guest users on the server. The constant UNLEN specifies the maximum number of characters in the string.
sv402_chdevs
Specifies how many character-oriented devices can be shared on the server.
sv402_chdevq
Specifies how many character-oriented device queues can coexist on the server.
sv402_chdevjobs
Specifies how many character-oriented device jobs can be pending at one time on the server.
sv402_connections
Specifies the number of connections allowed on the server.
sv402_shares
Specifies the number of share names the server can accommodate.
sv402_openfiles
Specifies the number of files that can be open at once on the server.
sv402_sessopens
Specifies the number of files that one session can open.
sv402_sessvcs
Specifies the maximum number of virtual circuits permitted per client.
sv402_sessreqs
Specifies the number of simultaneous requests a client can make on a single virtual circuit.
sv402_opensearch
Specifies the number of search operations that can be carried out simultaneously.
sv402_activelocks
Specifies the number of file locks that can be active at the same time.
sv402_numreqbuf
Specifies the number of server buffers provided.
sv402_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv402_numbigbuf
Specifies the number of 64K server buffers provided.
sv402_numfiletasks
Specifies the number of processes that can access the operating system at one time.
sv402_alertsched
Specifies the interval, in seconds, for notifying an administrator of a network event.
sv402_erroralert
Specifies the number of entries that can be written to the error log, in any one interval, before notifying an administrator. (The interval is specified by the sv402_alertsched member.)
sv402_logonalert
Specifies how many invalid logon attempts to allow a user before notifying an administrator.
sv402_accessalert
Specifies the number of invalid file access attempts to allow before notifying an administrator.
sv402_diskalert
Specifies the point at which the system sends a message notifying an administrator that free space on a disk is low. This value is expressed as the number of kilobytes of free disk space remaining on the disk.
sv402_netioalert
Specifies, in tenths of a percent, the network I/O error ratio that is allowed before notifying an administrator.
sv402_maxauditsz
Specifies, in kilobytes, the maximum size of the audit file. The audit file traces user activity.
sv402_srvheuristics
Pointer to a Unicode string containing flags that control operations on a server.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_403

The SERVER_INFO_403 structure contains information about a specified server.

typedef struct _SERVER_INFO_403 {
  DWORD          sv403_ulist_mtime;
  DWORD          sv403_glist_mtime;
  DWORD          sv403_alist_mtime;
  LPWSTR         sv403_alerts;
  DWORD          sv403_security;
  DWORD          sv403_numadmin;
  DWORD          sv403_lanmask;
  LPWSTR         sv403_guestacct;
  DWORD          sv403_chdevs;
  DWORD          sv403_chdevq;
  DWORD          sv403_chdevjobs;
  DWORD          sv403_connections;
  DWORD          sv403_shares;
  DWORD          sv403_openfiles;
  DWORD          sv403_sessopens;
  DWORD          sv403_sessvcs;
  DWORD          sv403_sessreqs;
  DWORD          sv403_opensearch;
  DWORD          sv403_activelocks;
  DWORD          sv403_numreqbuf;
  DWORD          sv403_sizreqbuf;
  DWORD          sv403_numbigbuf;
  DWORD          sv403_numfiletasks;
  DWORD          sv403_alertsched;
  DWORD          sv403_erroralert;
  DWORD          sv403_logonalert;
  DWORD          sv403_accessalert;
  DWORD          sv403_diskalert;
  DWORD          sv403_netioalert;
  DWORD          sv403_maxauditsz;
  LPWSTR         sv403_srvheuristics;
  DWORD          sv403_auditedevents;
  DWORD          sv403_autoprofile;
  LPWSTR         sv403_autopath;
} SERVER_INFO_403, *PSERVER_INFO_403, *LPSERVER_INFO_403;

Members

sv403_ulist_mtime
Specifies the last time the user list was modified. The value is expressed as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT, and applies to servers running with user-level security.
sv403_glist_mtime
Specifies the last time the group list was modified. The value is expressed as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT, and applies to servers running with user-level security.
sv403_alist_mtime
Specifies the last time the access control list was modified. The value is expressed as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT, and applies to servers running with user-level security.
sv403_alerts
Pointer to a Unicode string specifying the list of user names on the server. Spaces separate the names.
sv403_security
Specifies the security type of the server. This member can be one of the following values.
Value | Meaning
SV_SHARESECURITY | Share-level security
SV_USERSECURITY | User-level security

sv403_numadmin
Specifies the number of administrators the server can accommodate at one time.
sv403_lanmask
Specifies the order in which the network device drivers are served.
sv403_guestacct
Pointer to a Unicode string specifying the name of a reserved account for guest users on the server. The UNLEN constant specifies the maximum number of characters in the string.
sv403_chdevs
Specifies the number of character devices that can be shared on the server.
sv403_chdevq
Specifies the number of character device queues that can coexist on the server.
sv403_chdevjobs
Specifies the number of character device jobs that can be pending at one time on the server.
sv403_connections
Specifies the number of connections allowed on the server.
sv403_shares
Specifies the number of share names the server can accommodate.
sv403_openfiles
Specifies the number of files that can be open at once on the server.
sv403_sessopens
Specifies the number of files that one session can open.
sv403_sessvcs
Specifies the maximum number of virtual circuits permitted per client.
sv403_sessreqs
Specifies the number of simultaneous requests a client can make on a single virtual circuit.
sv403_opensearch
Specifies the number of search operations that can be carried out simultaneously.
sv403_activelocks
Specifies the number of file locks that can be active at the same time.
sv403_numreqbuf
Specifies the number of server buffers that are provided.
sv403_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv403_numbigbuf
Specifies the number of 64K server buffers provided.
sv403_numfiletasks
Specifies the number of processes that can access the operating system at the same time.
sv403_alertsched
Specifies the alert interval, in seconds, for notifying an administrator of a network event.
sv403_erroralert
Specifies the number of entries that can be written to the error log, in any one interval, before notifying an administrator. (The interval is specified by the sv403_alertsched member.)
sv403_logonalert
Specifies how many invalid attempts that a user tries to logon before notifying an administrator.
sv403_accessalert
Specifies how many invalid file access attempts to allow before notifying an administrator.
sv403_diskalert
Specifies the point at which the system sends a message notifying an administrator that free space on a disk is low. This value is expressed as the number of kilobytes of free disk space remaining on the disk.
sv403_netioalert
Specifies the network I/O error ratio, in tenths of a percent, that is allowed before notifying an administrator.
sv403_maxauditsz
Specifies, in kilobytes, the maximum audit file size. The audit file traces user activity.
sv403_srvheuristics
Pointer to a Unicode string containing flags that are used to control operations on a server.
sv403_auditedevents
Specifies the audit event control mask.
sv403_autoprofile
Specifies a value that controls the action of the server on the profile. The following values are predefined.
Value | Meaning
SW_AUTOPROF_LOAD_MASK | The server loads the profile.
SW_AUTOPROF_SAVE_MASK | The server saves the profile.

sv403_autopath
Pointer to a Unicode string that contains the path for the profile.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_502

The SERVER_INFO_502 structure is obsolete. The structure contains information about a specified server.

typedef struct _SERVER_INFO_502 {
  DWORD    sv502_sessopens;
  DWORD    sv502_sessvcs;
  DWORD    sv502_opensearch;
  DWORD    sv502_sizreqbuf;
  DWORD    sv502_initworkitems;
  DWORD    sv502_maxworkitems;
  DWORD    sv502_rawworkitems;
  DWORD    sv502_irpstacksize;
  DWORD    sv502_maxrawbuflen;
  DWORD    sv502_sessusers;
  DWORD    sv502_sessconns;
  DWORD    sv502_maxpagedmemoryusage;
  DWORD    sv502_maxnonpagedmemoryusage;
  BOOL     sv502_enablesoftcompat;
  BOOL     sv502_enableforcedlogoff;
  BOOL     sv502_timesource;
  BOOL     sv502_acceptdownlevelapis;
  BOOL     sv502_lmannounce;
} SERVER_INFO_502, *PSERVER_INFO_502, *LPSERVER_INFO_502;

Members

sv502_sessopens
Specifies the number of files that can be open in one session.
sv502_sessvcs
Specifies the maximum number of virtual circuits permitted per client.
sv502_opensearch
Specifies the number of search operations that can be carried out simultaneously.
sv502_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv502_initworkitems
Specifies the initial number of receive buffers, or work items, used by the server.
sv502_maxworkitems
Specifies the maximum number of receive buffers, or work items, the server can allocate. If this limit is reached, the transport must initiate flow control at a significant performance cost.
sv502_rawworkitems
Specifies the number of special work items the server uses for raw mode I/O. A large value for this member can increase performance, but it requires more memory.
sv502_irpstacksize
Specifies the number of stack locations that the server allocated in I/O request packets (IRPs).
sv502_maxrawbuflen
Specifies the maximum raw mode buffer size, in bytes.
sv502_sessusers
Specifies the maximum number of users that can be logged on to the server using a single virtual circuit.
sv502_sessconns
Specifies the maximum number of tree connections that can be made on the server using a single virtual circuit.
sv502_maxpagedmemoryusage
Specifies the maximum size of pageable memory that the server can allocate at any one time.
sv502_maxnonpagedmemoryusage
Specifies the maximum size of nonpaged memory that the server can allocate at any one time.
sv502_enablesoftcompat
TBD
sv502_enableforcedlogoff
Specifies whether the server should force a client to disconnect, even if the client has open files, once the client's logon time has expired.
sv502_timesource
Specifies whether the server is a reliable time source.
sv502_acceptdownlevelapis
Specifies whether the server accepts function calls from previous-generation LAN Manager clients.
sv502_lmannounce
Specifies whether the server is visible to LAN Manager 2.x clients.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo, NetServerSetInfo


SERVER_INFO_503

The SERVER_INFO_503 structure is obsolete. The structure contains information about the specified server.

typedef struct _SERVER_INFO_503 {
  DWORD     sv503_sessopens;
  DWORD     sv503_sessvcs;
  DWORD     sv503_opensearch;
  DWORD     sv503_sizreqbuf;
  DWORD     sv503_initworkitems;
  DWORD     sv503_maxworkitems;
  DWORD     sv503_rawworkitems;
  DWORD     sv503_irpstacksize;
  DWORD     sv503_maxrawbuflen;
  DWORD     sv503_sessusers;
  DWORD     sv503_sessconns;
  DWORD     sv503_maxpagedmemoryusage;
  DWORD     sv503_maxnonpagedmemoryusage;
  BOOL      sv503_enablesoftcompat
  BOOL      sv503_enableforcedlogoff;
  BOOL      sv503_timesource;
  BOOL      sv503_acceptdownlevelapis;
  BOOL      sv503_lmannounce;
  LPWSTR    sv503_domain;
  DWORD     sv503_maxcopyreadlen;
  DWORD     sv503_maxcopywritelen;
  DWORD     sv503_minkeepsearch;
  DWORD     sv503_maxkeepsearch;
  DWORD     sv503_minkeepcomplsearch;
  DWORD     sv503_maxkeepcomplsearch;
  DWORD     sv503_threadcountadd;
  DWORD     sv503_numblockthreads;
  DWORD     sv503_scavtimeout;
  DWORD     sv503_minrcvqueue;
  DWORD     sv503_minfreeworkitems;
  DWORD     sv503_xactmemsize;
  DWORD     sv503_threadpriority;
  DWORD     sv503_maxmpxct;
  DWORD     sv503_oplockbreakwait;
  DWORD     sv503_oplockbreakresponsewait;
  BOOL      sv503_enableoplocks;
  BOOL      sv503_enableoplockforceclose;
  BOOL      sv503_enablefcbopens;
  BOOL      sv503_enableraw;
  BOOL      sv503_enablesharednetdrives;
  DWORD     sv503_minfreeconnections;
  DWORD     sv503_maxfreeconnections;
} SERVER_INFO_503, *PSERVER_INFO_503, *LPSERVER_INFO_503;

Members

sv503_sessopens
Specifies the number of files that can be open in one session.
sv503_sessvcs
Specifies the maximum number of virtual circuits permitted per client.
sv503_opensearch
Specifies the number of search operations that can be carried out simultaneously.
sv503_sizreqbuf
Specifies the size, in bytes, of each server buffer.
sv503_initworkitems
Specifies the initial number of receive buffers, or work items, used by the server.
sv503_maxworkitems
Specifies the maximum number of receive buffers, or work items, the server can allocate. If this limit is reached, the transport must initiate flow control at a significant performance cost.
sv503_rawworkitems
Specifies the number of special work items the server uses for raw mode I/O. A larger value for this member can increase performance but it requires more memory.
sv503_irpstacksize
Specifies the number of stack locations that the server allocated in I/O request packets (IRPs).
sv503_maxrawbuflen
Specifies the maximum raw mode buffer size, in bytes.
sv503_sessusers
Specifies the maximum number of users that can be logged on to the server using a single virtual circuit.
sv503_sessconns
Specifies the maximum number of tree connections that can be made on the server using a single virtual circuit.
sv503_maxpagedmemoryusage
Specifies the maximum size of pageable memory that the server can allocate at any one time.
sv503_maxnonpagedmemoryusage
Specifies the maximum size of nonpaged memory that the server can allocate at any time.
sv503_enablesoftcompat
TBD
sv503_enableforcedlogoff
Specifies whether the server should force a client to disconnect, even if the client has open files, once the client's logon time has expired.
sv503_timesource
Specifies whether the server is a reliable time source.
sv503_acceptdownlevelapis
Specifies whether the server accepts function calls from previous-generation LAN Manager clients.
sv503_lmannounce
Specifies whether the server is visible to LAN Manager 2.x clients.
sv503_domain
Pointer to a Unicode character string that specifies the name of the server's domain.
sv503_maxcopyreadlen
TBD
sv503_maxcopywritelen
TBD
sv503_minkeepsearch
TBD
sv503_maxkeepsearch
Specifies the length of time the server retains information about incomplete search operations.
sv503_minkeepcomplsearch
TBD
sv503_maxkeepcomplsearch
TBD
sv503_threadcountadd
TBD
sv503_numblockthreads
TBD
sv503_scavtimeout
Specifies the period of time that the scavenger remains idle before waking up to service requests.
sv503_minrcvqueue
Specifies the minimum number of free receive work items the server requires before it begins to allocate more.
sv503_minfreeworkitems
Specifies the minimum number of available receive work items that the server requires to begin processing a server message block.
sv503_xactmemsize
Specifies the size of the shared memory region used to process server functions.
sv503_threadpriority
Specifies the priority of all server threads in relation to the base priority of the process.
sv503_maxmpxct
Specifies the maximum number of outstanding requests that any one client can send to the server. For example, 10 means you can have 10 unanswered requests at the server. When any single client has 10 requests queued within the server, the client must wait for a server response before sending another request.
sv503_oplockbreakwait
Specifies the period of time to wait before timing out an opportunistic lock break request.
sv503_oplockbreakresponsewait
TBD
sv503_enableoplocks
Specifies whether the server allows clients to use opportunistic locks on files. Opportunistic locks are a significant performance enhancement, but have the potential to cause lost cached data on some networks, particularly wide-area networks.
sv503_enableoplockforceclose
TBD
sv503_enablefcbopens
Specifies whether several MS-DOS File Control Blocks (FCBs) are placed in a single location accessible to the server. If enabled, this can save resources on the server.
sv503_enableraw
Specifies whether the server processes raw Server Message Blocks (SMBs). If enabled, this allows more data to transfer per transaction and also improves performance. However, it is possible that processing raw SMBs can impede performance on certain networks. The server maintains the value of this member.
sv503_enablesharednetdrives
Specifies whether the server allows redirected server drives to be shared.
sv503_minfreeconnections
Specifies the minimum number of free connection blocks maintained per endpoint. The server sets these aside to handle bursts of requests by clients to connect to the server.
sv503_maxfreeconnections
Specifies the maximum number of free connection blocks maintained per endpoint. The server sets these aside to handle bursts of requests by clients to connect to the server.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1005

The SERVER_INFO_1005 structure contains a comment that describes the specified server.

typedef struct _SERVER_INFO_1005 {
  LPWSTR    sv1005_comment;
} SERVER_INFO_1005, *PSERVER_INFO_1005, *LPSERVER_INFO_1005;

Members

sv1005_comment
Pointer to a Unicode string that contains a comment describing the server. The comment can be null.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1010

The SERVER_INFO_1010 structure contains the auto-disconnect time associated with the specified server.

typedef struct _SERVER_INFO_1010 {
  LONG    sv1010_disc;
} SERVER_INFO_1010, *PSERVER_INFO_1010, *LPSERVER_INFO_1010;

Members

sv1010_disc
Specifies the auto-disconnect time, in minutes.

If a session is idle longer than the period of time specified by this member, the server disconnects the session. If the value of this member is SV_NODISC, auto-disconnect is not enabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1016

The SERVER_INFO_1016 structure contains information about whether the server is visible to other computers in the same network domain.

typedef struct _SERVER_INFO_1016 {
  BOOL    sv1016_hidden;
} SERVER_INFO_1016, *PSERVER_INFO_1016, *LPSERVER_INFO_1016;

Members

sv1016_hidden
Specifies whether the server is visible to other computers in the same network domain. This member can be one of the following values.
Value | Meaning
SV_VISIBLE | The server is visible.
SV_HIDDEN | The server is not visible.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1017

The SERVER_INFO_1017 structure contains the network announce rate associated with the specified server.

typedef struct _SERVER_INFO_1017 {
  DWORD    sv1017_announce;
} SERVER_INFO_1017, *PSERVER_INFO_1017, *LPSERVER_INFO_1017;

Members

sv1017_announce
Specifies the network announce rate, in seconds. This rate determines how often the server is announced to other computers on the network.

For more information about how much the announce rate can vary from the period of time specified by this member, see SERVER_INFO_1018.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo, SERVER_INFO_1018


SERVER_INFO_1018

The SERVER_INFO_1018 structure contains information about how much the announce rate can vary for the specified server.

typedef struct _SERVER_INFO_1018 {
  DWORD    sv1018_anndelta;
} SERVER_INFO_1018, *PSERVER_INFO_1018, *LPSERVER_INFO_1018;

Members

sv1018_anndelta
Specifies the delta value for the announce rate, in milliseconds. This value specifies how much the announce rate can vary from the period of time specified in the svX_announce member.

The delta value allows randomly varied announce rates. For example, if the svX_announce member has the value 10 and the svX_anndelta member has the value 1, the announce rate can vary from 9.999 seconds to 10.001 seconds. For more information, see SERVER_INFO_102 and SERVER_INFO_1017.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo, SERVER_INFO_102, SERVER_INFO_1017


SERVER_INFO_1107

The SERVER_INFO_1107 structure specifies the number of users that can simultaneously log on to the specified server.

typedef struct _SERVER_INFO_1107 {
  DWORD    sv1107_users;
} SERVER_INFO_1107, *PSERVER_INFO_1107, *LPSERVER_INFO_1107;

Members

sv1107_users
Specifies the number of users who can attempt to log on to the system server. Note that it is the license server that determines how many of these users can actually log on.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1501

The SERVER_INFO_1501 structure specifies the number of files that can be open in one session on the specified server.

typedef struct _SERVER_INFO_1501 {
  DWORD    sv1501_sessopens;
} SERVER_INFO_1501, *PSERVER_INFO_1501, *LPSERVER_INFO_1501;

Members

sv1501_sessopens
Specifies the number of files that one session can open.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1502

The SERVER_INFO_1502 structure specifies the maximum number of virtual circuits per client for the specified server.

typedef struct _SERVER_INFO_1502 {
  DWORD    sv1502_sessvcs;
} SERVER_INFO_1502, *PSERVER_INFO_1502, *LPSERVER_INFO_1502;

Members

sv1502_sessvcs
Specifies the maximum number of virtual circuits permitted per client.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1503

The SERVER_INFO_1503 structure specifies the number of search operations that can be carried out simultaneously.

typedef struct _SERVER_INFO_1503 {
  DWORD    sv1503_opensearch;
} SERVER_INFO_1503, *PSERVER_INFO_1503, *LPSERVER_INFO_1503;

Members

sv1503_opensearch
Specifies the number of search operations that can be carried out simultaneously.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1506

The SERVER_INFO_1506 structure contains information about the maximum number of work items the specified server can allocate.

typedef struct _SERVER_INFO_1506 {
  DWORD    sv1506_maxworkitems;
} SERVER_INFO_1506, *PSERVER_INFO_1506, *LPSERVER_INFO_1506;

Members

sv1506_maxworkitems
Specifies the maximum number of receive buffers, or work items, the server can allocate. If this limit is reached, the transport protocol must initiate flow control at a significant cost to performance.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1509

The SERVER_INFO_1509 structure specifies the maximum raw mode buffer size.

typedef struct _SERVER_INFO_1509 {
  DWORD    sv1509_maxrawbuflen;
} SERVER_INFO_1509, *PSERVER_INFO_1509, *LPSERVER_INFO_1509;

Members

sv1509_maxrawbuflen
Specifies the maximum raw mode buffer size, in bytes.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1510

The SERVER_INFO_1510 structure specifies the maximum number of users that can be logged on to the specified server using a single virtual circuit.

typedef struct _SERVER_INFO_1510 {
  DWORD    sv1510_sessusers;
} SERVER_INFO_1510, *PSERVER_INFO_1510, *LPSERVER_INFO_1510;

Members

sv1510_sessusers
Specifies the maximum number of users that can be logged on to a server using a single virtual circuit.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1511

The SERVER_INFO_1511 structure specifies the maximum number of tree connections that users can make with a single virtual circuit.

typedef struct _SERVER_INFO_1511 {
  DWORD    sv1511_sessconns;
} SERVER_INFO_1511, *PSERVER_INFO_1511, *LPSERVER_INFO_1511;

Members

sv1511_sessconns
Specifies the maximum number of tree connections that users can make with a single virtual circuit.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1512

The SERVER_INFO_1512 structure contains the maximum size of nonpaged memory that the specified server can allocate at a particular time.

typedef struct _SERVER_INFO_1512 {
  DWORD    sv1512_maxnonpagedmemoryusage;
} SERVER_INFO_1512, *PSERVER_INFO_1512, *LPSERVER_INFO_1512;

Members

sv1512_maxnonpagedmemoryusage
Specifies the maximum size of nonpaged memory that the server can allocate at any one time. Adjust this member if you want to administer memory quota control.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1513

The SERVER_INFO_1513 structure contains the maximum size of pageable memory that the specified server can allocate at a particular time.

typedef struct _SERVER_INFO_1513 {
  DWORD    sv1513_maxpagedmemoryusage;
} SERVER_INFO_1513, *PSERVER_INFO_1513, *LPSERVER_INFO_1513;

Members

sv1513_maxpagedmemoryusage
Specifies the maximum size of pageable memory that the server allocates at any particular time. Adjust this member if you want to administer memory quota control.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1515

The SERVER_INFO_1515 structure specifies whether the server should force a client to disconnect once the client's logon time has expired.

typedef struct _SERVER_INFO_1515 {
  BOOL    sv1515_enableforcedlogoff;
} SERVER_INFO_1515, *PSERVER_INFO_1515, *LPSERVER_INFO_1515;

Members

sv1515_enableforcedlogoff
Specifies whether the server should force a client to disconnect, even if the client has open files, once the client's logon time has expired.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1516

The SERVER_INFO_1516 structure specifies whether the server is a reliable time source.

typedef struct _SERVER_INFO_1516 {
  BOOL    sv1516_timesource;
} SERVER_INFO_1516, *PSERVER_INFO_1516, *LPSERVER_INFO_1516;

Members

sv1516_timesource
Specifies whether the server is a reliable time source.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1518

The SERVER_INFO_1518 structure specifies the interval between operating system server announcements.

typedef struct _SERVER_INFO_1518 {
  BOOL    sv1518_lmannounce;
} SERVER_INFO_1518, *PSERVER_INFO_1518, *LPSERVER_INFO_1518;

Members

sv1518_lmannounce
Specifies whether the server is visible to LAN Manager 2.x clients.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1523

The SERVER_INFO_1523 structure specifies the length of time the server retains information about incomplete search operations.

typedef struct _SERVER_INFO_1523 {
  DWORD    sv1523_maxkeepsearch;
} SERVER_INFO_1523, *PSERVER_INFO_1523, *LPSERVER_INFO_1523;

Members

sv1523_maxkeepsearch
Specifies the length of time the server retains information about incomplete search operations.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1528

The SERVER_INFO_1528 structure specifies the period of time that the scavenger remains idle before waking up to service requests.

typedef struct _SERVER_INFO_1528 {
  DWORD    sv1528_scavtimeout;
} SERVER_INFO_1528, *PSERVER_INFO_1528, *LPSERVER_INFO_1528;

Members

sv1528_scavtimeout
Specifies the period of time, in seconds, that the scavenger remains idle before waking up to service requests. A smaller value for this member improves the response of the server to various events but costs CPU cycles.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1529

The SERVER_INFO_1529 structure specifies the minimum number of free receive work items the server requires before it begins allocating more items.

typedef struct _SERVER_INFO_1529 {
  DWORD    sv1529_minrcvqueue;
} SERVER_INFO_1529, *PSERVER_INFO_1529, *LPSERVER_INFO_1529;

Members

sv1529_minrcvqueue
Specifies the minimum number of free receive work items the server requires before it begins allocating more. A larger value for this member helps ensure that there will always be work items available, but a value that is too large is inefficient.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1530

The SERVER_INFO_1530 structure specifies the minimum number of available receive work items the server requires to begin processing a server message block.

typedef struct _SERVER_INFO_1530 {
  DWORD    sv1530_minfreeworkitems;
} SERVER_INFO_1530, *PSERVER_INFO_1530, *LPSERVER_INFO_1530;

Members

sv1530_minfreeworkitems
Specifies the minimum number of available receive work items that the server requires to begin processing a server message block. A larger value for this member ensures that work items are available more frequently for nonblocking requests, but it also increases the likelihood that blocking requests will be rejected.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1533

The SERVER_INFO_1533 structure specifies the maximum number of outstanding requests a client can send to the server.

typedef struct _SERVER_INFO_1533 {
  DWORD    sv1533_maxmpxct;
} SERVER_INFO_1533, *PSERVER_INFO_1533, *LPSERVER_INFO_1533;

Members

sv1533_maxmpxct
Specifies the maximum number of outstanding requests any one client can send to the server. For example, 10 means you can have 10 unanswered requests at the server. When any single client has 10 requests queued within the server, the client must wait for a server response before sending another request.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1536

The SERVER_INFO_1536 structure specifies whether the server allows clients to use opportunistic locks (oplocks) on files.

typedef struct _SERVER_INFO_1536 {
  BOOL    sv1536_enableoplocks;
} SERVER_INFO_1536, *PSERVER_INFO_1536, *LPSERVER_INFO_1536;

Members

sv1536_enableoplocks
Specifies whether the server allows clients to use oplocks on files. Opportunistic locks are a significant performance enhancement, but have the potential to cause lost cached data on some networks, particularly wide-area networks.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1538

The SERVER_INFO_1538 structure specifies whether several MS-DOS File Control Blocks (FCBs) are placed in a single location.

typedef struct _SERVER_INFO_1538 {
  BOOL    sv1538_enablefcbopens;
} SERVER_INFO_1538, *PSERVER_INFO_1538, *LPSERVER_INFO_1538;

Members

sv1538_enablefcbopens
Specifies whether several MS-DOS File Control Blocks (FCBs) are placed in a single location accessible to the server.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1539

The SERVER_INFO_1539 structure specifies whether the server processes raw Server Message Blocks (SMBs).

typedef struct _SERVER_INFO_1539 {
  BOOL    sv1539_enableraw;
} SERVER_INFO_1539, *PSERVER_INFO_1539, *LPSERVER_INFO_1539;

Members

sv1539_enableraw
Specifies whether the server processes raw SMBs. If enabled, this member allows more data to be transferred per transaction and improves performance. However, it is possible that processing raw SMBs can impede performance on certain networks. The server maintains the value of this member.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1540

The SERVER_INFO_1540 structure specifies whether the server allows redirected server drives to be shared.

typedef struct _SERVER_INFO_1540 {
  BOOL    sv1540_enablesharednetdrives;
} SERVER_INFO_1540, *PSERVER_INFO_1540, *LPSERVER_INFO_1540;

Members

sv1540_enablesharednetdrives
Specifies whether the server allows redirected server drives to be shared.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1541

The SERVER_INFO_1541 structure specifies the minimum number of free connection blocks the server sets aside to handle bursts of requests by clients to connect to the server.

typedef struct _SERVER_INFO_1541 {
  BOOL    sv1541_minfreeconnections;
} SERVER_INFO_1541, *PSERVER_INFO_1541, *LPSERVER_INFO_1541;

Members

sv1541_minfreeconnections
Specifies the minimum number of free connection blocks maintained per endpoint. The server sets these aside to handle bursts of requests by clients to connect to the server.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1542

The SERVER_INFO_1542 structure specifies the maximum number of free connection blocks the server sets aside to handle bursts of requests by clients to connect to the server.

typedef struct _SERVER_INFO_1542 {
  BOOL    sv1542_maxfreeconnections;
} SERVER_INFO_1542, *PSERVER_INFO_1542, *LPSERVER_INFO_1542;

Members

sv1542_maxfreeconnections
Specifies the maximum number of free connection blocks maintained per endpoint. The server sets these aside to handle bursts of requests by clients to connect to the server.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1544

The SERVER_INFO_1544 structure specifies the initial number of tree connections to be allocated in the connection table.

typedef struct _SERVER_INFO_1544 {
  DWORD    sv1544_initconntable;
} SERVER_INFO_1544, *PSERVER_INFO_1544, *LPSERVER_INFO_1544;

Members

sv1544_initconntable
Specifies the initial number of tree connections to be allocated in the connection table. The server automatically increases the table as necessary, so setting the member to a higher value is an optimization.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1550

The SERVER_INFO_1550 structure specifies the percentage of free disk space remaining before an alert message is sent.

typedef struct _SERVER_INFO_1550 {
  DWORD    sv1550_diskspacethreshold;
} SERVER_INFO_1550, *PSERVER_INFO_1550, *LPSERVER_INFO_1550;

Members

sv1550_diskspacethreshold
Specifies the percentage of free disk space remaining before an alert message is sent.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_INFO_1552

The SERVER_INFO_1552 structure specifies the maximum time allowed for a link delay.

typedef struct _SERVER_INFO_1552 {
  DWORD    sv1552_maxlinkdelay;
} SERVER_INFO_1552, *PSERVER_INFO_1552, *LPSERVER_INFO_1552;

Members

sv1552_maxlinkdelay
Specifies the maximum time allowed for a link delay, in seconds. If delays exceed this number, the server disables raw I/O for this connection.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server Functions, NetServerGetInfo


SERVER_TRANSPORT_INFO_0

The SERVER_TRANSPORT_INFO_0 structure contains information about the specified transport protocol, including name, address, and location on the network.

typedef struct _SERVER_TRANSPORT_INFO_0 {
  DWORD     svti0_numberofvcs;
  LPWSTR    svti0_transportname;
  LPBYTE    svti0_transportaddress;
  DWORD     svti0_transportaddresslength;
  LPWSTR    svti0_networkaddress;
} SERVER_TRANSPORT_INFO_0, *PSERVER_TRANSPORT_INFO_0, *LPSERVER_TRANSPORT_INFO_0;

Members

svti0_numberofvcs
Specifies a DWORD value that indicates the number of clients connected to the server that are using the transport protocol specified by the svti0_transportname member.
svti0_transportname
Pointer to a null-terminated Unicode character string that contains the name of a Windows NT transport device; for example,
\Device\NetBT_Tcpip_{2C9725F4-151A-11D3-AEEC-C3B211BD350B}
svti0_transportaddress
Pointer to a variable that contains the address the server is using on the transport device specified by the svti0_transportname member.

This member is usually the NetBIOS name that the server is using. In these instances, the name must be 16 characters long, and the last character must be a blank character (0x20).

svti0_transportaddresslength
Specifies a DWORD value that contains the length, in bytes, of the svti0_transportaddress member. For NetBIOS names, the value of this member is 16 (decimal).
svti0_networkaddress
Pointer to a null-terminated Unicode character string that contains the address the network adapter is using. The string is transport-specific.

You can retrieve this value only with a call to the NetServerTransportEnum function. You cannot set this value with a call to the NetServerTransportAdd function or the NetServerTransportAddEx function.)

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server and Workstation Transport Functions, NetServerTransportAdd, NetServerTransportAddEx, NetServerTransportDel, NetServerTransportEnum, SERVER_TRANSPORT_INFO_1, SERVER_TRANSPORT_INFO_2


SERVER_TRANSPORT_INFO_1

The SERVER_TRANSPORT_INFO_1 structure contains information about the specified transport protocol, including name and address.

typedef struct _SERVER_TRANSPORT_INFO_1 {
  DWORD     svti1_numberofvcs;
  LPSTR     svti1_transportname;
  LPBYTE    svti1_transportaddress;
  DWORD     svti1_transportaddresslength;
  LPSTR     svti1_networkaddress;
  LPSTR     svti1_domain;
} SERVER_TRANSPORT_INFO_1, *PSERVER_TRANSPORT_INFO_1, *LPSERVER_TRANSPORT_INFO_1;

Members

svti1_numberofvcs
Specifies a DWORD value that indicates the number of clients connected to the server that are using the transport protocol specified by the svti1_transportname member.
svti1_transportname
Pointer to a null-terminated character string that contains the name of a Windows NT transport device; for example,
\Device\NetBT_Tcpip_{2C9725F4-151A-11D3-AEEC-C3B211BD350B}
svti1_transportaddress
Pointer to a variable that contains the address the server is using on the transport device specified by the svti1_transportname member.

This member is usually the NetBIOS name that the server is using. In these instances, the name must be 16 characters long, and the last character must be a blank character (0x20).

svti1_transportaddresslength
Specifies a DWORD value that contains the length, in bytes, of the svti1_transportaddress member. For NetBIOS names, the value of this member is 16 (decimal).
svti1_networkaddress
Pointer to a null-terminated character string that contains the address the network adapter is using. The string is transport-specific.

You can retrieve this value only with a call to the NetServerTransportEnum function. You cannot set this value with a call to the NetServerTransportAdd function or the NetServerTransportAddEx function.)

svti1_domain
Pointer to a null-terminated character string that contains the name of the domain to which the server should announce its presence. (When you call NetServerTransportEnum, this member is the name of the domain to which the server is announcing its presence.)

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server and Workstation Transport Functions, NetServerTransportAddEx, NetServerTransportDel, NetServerTransportEnum, SERVER_TRANSPORT_INFO_0, SERVER_TRANSPORT_INFO_2


SERVER_TRANSPORT_INFO_2

The SERVER_TRANSPORT_INFO_2 structure contains information about the specified transport protocol, including name and address. This information level is valid only for the NetServerTransportAddEx function.

typedef struct _SERVER_TRANSPORT_INFO_2 {
  DWORD     svti2_numberofvcs;
  LPSTR     svti2_transportname;
  LPBYTE    svti2_transportaddress;
  DWORD     svti2_transportaddresslength;
  LPSTR     svti2_networkaddress;
  LPSTR     svti2_domain;
  ULONG     svti2_flags;
} SERVER_TRANSPORT_INFO_2, *PSERVER_TRANSPORT_INFO_2, *LPSERVER_TRANSPORT_INFO_2;

Members

svti2_numberofvcs
Specifies a DWORD value that indicates the number of clients connected to the server that are using the transport protocol specified by the svti2_transportname member.
svti2_transportname
Pointer to a null-terminated character string that contains the name of a Windows NT transport device; for example,
\Device\NetBT_Tcpip_{2C9725F4-151A-11D3-AEEC-C3B211BD350B}
svti2_transportaddress
Pointer to a variable that contains the address the server is using on the transport device specified by the svti2_transportname member.

This member is usually the NetBIOS name that the server is using. In these instances, the name must be 16 characters long, and the last character must be a blank character (0x20).

svti2_transportaddresslength
Specifies a DWORD value that contains the length, in bytes, of the svti2_transportaddress member. For NetBIOS names, the value of this member is 16 (decimal).
svti2_networkaddress
Pointer to a null-terminated character string that contains the address the network adapter is using. The string is transport-specific.

You can retrieve this value only with a call to the NetServerTransportEnum function. You cannot set this value with a call to the NetServerTransportAdd function or the NetServerTransportAddEx function.)

svti2_domain
Pointer to a null-terminated character string that contains the name of the domain to which the server should announce its presence. (When you call NetServerTransportEnum, this member is the name of the domain to which the server is announcing its presence.)
svti2_flags
This member can be the following value.
Value | Meaning
SVTI2_REMAP_PIPE_NAMES | If this value is set for an endpoint, client requests arriving over the transport to open a named pipe are rerouted (remapped) to the local pipe name $$\ServerName\PipeName. For more information, see the following Remarks section.

Remarks

An example of the use of the SVTI2_REMAP_PIPE_NAMES value follows. Call the NetServerTransportAddEx function to add a transport to the server, specifying the address of "MyServer" in the svti2_transportaddress member, and SVTI2_REMAP_PIPE_NAMES in the svti2_flags member. When a client attempts to open "Pipe" on "\\MyServer" the client will actually open $$\MyServer\Pipe instead.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server and Workstation Transport Functions, NetServerTransportAddEx, NetServerTransportAdd, NetServerTransportDel, NetServerTransportEnum, SERVER_TRANSPORT_INFO_0, SERVER_TRANSPORT_INFO_1


SERVER_TRANSPORT_INFO_3

The SERVER_TRANSPORT_INFO_3 structure contains information about the specified transport protocol, including name, address and password (credentials). This information level is valid only for the NetServerTransportAddEx function.

typedef struct _SERVER_TRANSPORT_INFO_3 {
  DWORD     svti3_numberofvcs;
  LPSTR     svti3_transportname;
  LPBYTE    svti3_transportaddress;
  DWORD     svti3_transportaddresslength;
  LPSTR     svti3_networkaddress;
  LPSTR     svti3_domain;
  ULONG     svti3_flags;
  DWORD     svti3_passwordlength;
  BYTE      svti3_password[256];
} SERVER_TRANSPORT_INFO_3, *PSERVER_TRANSPORT_INFO_3, *LPSERVER_TRANSPORT_INFO_3;

Members

svti3_numberofvcs
Specifies a DWORD value that indicates the number of clients connected to the server that are using the transport protocol specified by the svti3_transportname member.
svti3_transportname
Pointer to a null-terminated character string that contains the name of a Windows NT transport device; for example,
\Device\NetBT_Tcpip_{2C9725F4-151A-11D3-AEEC-C3B211BD350B}
svti3_transportaddress
Pointer to a variable that contains the address the server is using on the transport device specified by the svti3_transportname member.

This member is usually the NetBIOS name that the server is using. In these instances, the name must be 16 characters long, and the last character must be a blank character (0x20).

svti3_transportaddresslength
Specifies a DWORD value that contains the length, in bytes, of the svti3_transportaddress member. For NetBIOS names, the value of this member is 16 (decimal).
svti3_networkaddress
Pointer to a null-terminated character string that contains the address the network adapter is using. The string is transport-specific. (You can retrieve this value only with a call to the NetServerTransportEnum function. You cannot set this value with a call to the NetServerTransportAdd function or the NetServerTransportAddEx function.)
svti3_domain
Pointer to a null-terminated character string that contains the name of the domain to which the server should announce its presence. (When you call NetServerTransportEnum, this member is the name of the domain to which the server is announcing its presence.)
svti3_flags
This member can be the following value.
Value | Meaning
SVTI2_REMAP_PIPE_NAMES | If this value is set for an endpoint, client requests arriving over the transport to open a named pipe are rerouted (remapped) to the local pipe name $$\ServerName\PipeName.

svti3_passwordlength
Specifies a DWORD value that indicates the number of valid bytes in the svti3_password member.
svti3_password
Specifies the credentials to use for the new transport address. If the svti3_passwordlength member is zero, the credentials for the server are used.

Remarks

For an example of the use of the SVTI2_REMAP_PIPE_NAMES value see SERVER_TRANSPORT_INFO_2.

The svti3_passwordlength and svti3_password members are necessary for a client and server to perform mutual authentication.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmserver.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server and Workstation Transport Functions, NetServerTransportAddEx, NetServerTransportAdd, NetServerTransportDel, NetServerTransportEnum, SERVER_TRANSPORT_INFO_0, SERVER_TRANSPORT_INFO_1, SERVER_TRANSPORT_INFO_2


SESSION_INFO_0

The SESSION_INFO_0 structure contains the name of the computer that established the session.

typedef struct _SESSION_INFO_0 {
  LPWSTR    sesi0_cname;
} SESSION_INFO_0, *PSESSION_INFO_0, *LPSESSION_INFO_0;

Members

sesi0_cname
Pointer to a Unicode string that contains the name of the computer that established the session.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionEnum, NetSessionGetInfo


session_info_0

Windows 95/98/Me: The session_info_0 structure contains the name of the computer that established the session.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the SESSION_INFO_0 structure instead.

struct _session_info_0 {
  char FAR *      sesi0_cname;
};

Members

sesi0_cname
Pointer to a string specifying the name of the computer that established the session.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, session_info_1, session_info_2, session_info_10, session_info_50, NetSessionGetInfo


SESSION_INFO_1

The SESSION_INFO_1 structure contains information about the session, including name of the computer; name of the user; and open files, pipes, and devices on the computer.

typedef struct _SESSION_INFO_1 {
  LPWSTR    sesi1_cname;
  LPWSTR    sesi1_username;
  DWORD     sesi1_num_opens;
  DWORD     sesi1_time;
  DWORD     sesi1_idle_time;
  DWORD     sesi1_user_flags;
} SESSION_INFO_1, *PSESSION_INFO_1, *LPSESSION_INFO_1;

Members

sesi1_cname
Pointer to a Unicode string specifying the name of the computer that established the session.
sesi1_username
Pointer to a Unicode string specifying the name of the user who established the session.
sesi1_num_opens
Specifies a DWORD value that contains the number of files, devices, and pipes opened during the session.
sesi1_time
Specifies a DWORD value that contains the number of seconds the session has been active.
sesi1_idle_time
Specifies a DWORD value that contains the number of seconds the session has been idle.
sesi1_user_flags
Specifies a DWORD value that describes how the user established the session. This member can be one of the following values.
Value | Meaning
SESS_GUEST | The user specified by the sesi1_username member established the session using a guest account.
SESS_NOENCRYPTION | The user specified by the sesi1_username member established the session without using password encryption.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionEnum, NetSessionGetInfo


session_info_1

Windows 95/98/Me: The session_info_1 structure contains information about the session, including name of the computer, name of the user, open files, and active and idle times for the session.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the SESSION_INFO_1 structure or the SESSION_INFO_502 structure instead.

struct _session_info_1 {
  char FAR *      sesi1_cname;
  char FAR *      sesi1_username;
  unsigned short  sesi1_num_conns;
  unsigned short  sesi1_num_opens;
  unsigned short  sesi1_num_users;
  unsigned long   sesi1_time;
  unsigned long   sesi1_idle_time;
  unsigned long   sesi1_user_flags;
};

Members

sesi1_cname
Pointer to a string specifying the name of the computer that established the session.
sesi1_username
Pointer to a string specifying the name of the user who established the session.
sesi1_num_conns
Specifies the number of connections made during the session.
sesi1_num_opens
Specifies the number of files opened during the session.
sesi1_num_users
Specifies the number of users that have made a connection during the session.
sesi1_time
Specifies the number of seconds the session has been active.
sesi1_idle_time
Specifies the number of seconds the session has been idle.
sesi1_user_flags
Specifies a value that describes how the user established the session. This member can be one of the following values.
Value | Meaning
SESS_GUEST | The user specified by the sesi1_username member established the session using a guest account.
SESS_NOENCRYPTION | The user specified by the sesi1_username member established the session without using password encryption.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionGetInfo, session_info_0, session_info_2, session_info_10, session_info_50


SESSION_INFO_2

The SESSION_INFO_2 structure contains information about the session, including name of the computer; name of the user; open files, pipes, and devices on the computer; and the type of client that established the session.

typedef struct _SESSION_INFO_2{
  LPWSTR    sesi2_cname;
  LPWSTR    sesi2_username;
  DWORD     sesi2_num_opens;
  DWORD     sesi2_time;
  DWORD     sesi2_idle_time;
  DWORD     sesi2_user_flags;
  LPWSTR    sesi2_cltype_name;
} SESSION_INFO_2, *PSESSION_INFO_2, *LPSESSION_INFO_2;

Members

sesi2_cname
Pointer to a Unicode string specifying the name of the computer that established the session.
sesi2_username
Pointer to a Unicode string specifying the name of the user who established the session.
sesi2_num_opens
Specifies a DWORD value that contains the number of files, devices, and pipes opened during the session.
sesi2_time
Specifies a DWORD value that contains the number of seconds the session has been active.
sesi2_idle_time
Specifies a DWORD value that contains the number of seconds the session has been idle.
sesi2_user_flags
Specifies a DWORD value that describes how the user established the session. This member can be one of the following values.
Value | Meaning
SESS_GUEST | The user specified by the sesi2_username member established the session using a guest account.
SESS_NOENCRYPTION | The user specified by the sesi2_username member established the session without using password encryption.

sesi2_cltype_name
Pointer to a Unicode string that specifies the type of client that established the session. Following are the defined types for LAN Manager servers.
Value | Meaning
DOS LM 1.0 | LAN Manager for MS-DOS 1.0 clients
DOS LM 2.0 | LAN Manager for MS-DOS 2.0 clients
OS/2 LM 1.0 | LAN Manager for MS-OS/2 1.0 clients
OS/2 LM 2.0 | LAN Manager for MS-OS/2 2.0 clients

Sessions from LAN Manager servers running UNIX also will appear as LAN Manager 2.0.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionEnum, NetSessionGetInfo


session_info_2

Windows 95/98/Me: The session_info_2 structure contains information about the session, including name of the computer, name of the user, open files, active and idle times for the session, and the client type.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the SESSION_INFO_2 structure or the SESSION_INFO_502 structure instead.

struct _session_info_2 {
  char FAR *      sesi2_cname;
  char FAR *      sesi2_username;
  unsigned short  sesi2_num_conns;
  unsigned short  sesi2_num_opens;
  unsigned short  sesi2_num_users;
  unsigned long   sesi2_time;
  unsigned long   sesi2_idle_time;
  unsigned long   sesi2_user_flags;
  char FAR *      sesi2_cltype_name;
};

Members

sesi2_cname
Pointer to a string specifying the name of the computer that established the session.
sesi2_username
Pointer to a string specifying the name of the user who established the session.
sesi2_num_conns
Specifies the number of connections made during the session.
sesi2_num_opens
Specifies the number of files opened during the session.
sesi2_num_users
Specifies the number of users that have made a connection during the session.
sesi2_time
Specifies the number of seconds the session has been active.
sesi2_idle_time
Specifies the number of seconds the session has been idle.
sesi2_user_flags
Specifies a variable that describes how the user established the session. This member can be one of the following values.
Value | Meaning
SESS_GUEST | The user specified by the sesi2_username member established the session using a guest account.
SESS_NOENCRYPTION | The user specified by the sesi2_username member established the session without using password encryption.

sesi2_cltype_name
Pointer to a string that specifies the type of client that established the session. Following are the defined types for LAN Manager servers.
Value | Meaning
DOS LM 1.0 | LAN Manager for MS-DOS 1.0 clients
DOS LM 2.0 | LAN Manager for MS-DOS 2.0 clients
OS/2 LM 1.0 | LAN Manager for MS-OS/2 1.0 clients
OS/2 LM 2.0 | LAN Manager for MS-OS/2 2.0 clients

Sessions from LAN Manager servers running UNIX also will appear as LAN Manager 2.0.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionGetInfo, session_info_0, session_info_1, session_info_10, session_info_50


SESSION_INFO_10

The SESSION_INFO_10 structure contains information about the session, including name of the computer; name of the user; and active and idle times for the session.

typedef struct _SESSION_INFO_10 {
  LPWSTR    sesi10_cname;
  LPWSTR    sesi10_username;
  DWORD     sesi10_time;
  DWORD     sesi10_idle_time;
} SESSION_INFO_10, *PSESSION_INFO_10, *LPSESSION_INFO_10;

Members

sesi10_cname
Pointer to a Unicode string specifying the name of the computer that established the session.
sesi10_username
Pointer to a Unicode string specifying the name of the user who established the session.
sesi10_time
Specifies the number of seconds the session has been active.
sesi10_idle_time
Specifies the number of seconds the session has been idle.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionEnum, NetSessionGetInfo


session_info_10

Windows 95/98/Me: The session_info_10 structure contains information about the session, including name of the computer, name of the user, and active and idle times for the session.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the SESSION_INFO_10 structure instead.

struct _session_info_10 {
  char FAR *      sesi10_cname;
  char FAR *      sesi10_username;
  unsigned long   sesi10_time;
  unsigned long   sesi10_idle_time;
};

Members

sesi10_cname
Pointer to a string specifying the name of the computer that established the session.
sesi10_username
Pointer to a string specifying the name of the user who established the session.
sesi10_time
Specifies the number of seconds the session has been active.
sesi10_idle_time
Specifies the number of seconds the session has been idle.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionGetInfo, session_info_0, session_info_1, session_info_2, session_info_50


session_info_50

Windows 95/98/Me: The session_info_50 structure contains information about the session, including name of the computer, name of the user, open files on the computer, and the name of the transport protocol the client is using.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the SESSION_INFO_502 structure instead.

struct _session_info_50 {
  char FAR *      sesi50_cname;
  char FAR *      sesi50_username;
  unsigned long   sesi50_key;
  unsigned short  sesi50_num_conns;
  unsigned short  sesi50_num_opens;
  unsigned long   sesi50_time;
  unsigned long   sesi50_idle_time;
  unsigned char   sesi50_protocol;
  unsigned char   pad1;
};

Members

sesi50_cname
Pointer to a string specifying the name of the computer that established the session.
sesi50_username
Pointer to a string specifying the name of the user who established the session.
sesi50_key
Specifies a long integer returned by the NetSessionEnum function or the NetSessionGetInfo function. This value is required to delete a session. Specify this value in the sReserved parameter when you call the NetSessionDel function.
sesi50_num_conns
Specifies the number of connections made during the session.
sesi50_num_opens
Specifies the number of files opened during the session.
sesi50_time
Specifies the number of seconds the session has been active.
sesi50_idle_time
Specifies the number of seconds the session has been idle.
sesi50_protocol
Specifies the name of the transport that the client is using to communicate with the server.
pad1
Specifies padding inserted to align the next structure.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionEnum, NetSessionGetInfo, NetSessionDel, session_info_0, session_info_1, session_info_2, session_info_10


SESSION_INFO_502

The SESSION_INFO_502 structure contains information about the session, including name of the computer; name of the user; open files, pipes, and devices on the computer; and the name of the transport the client is using.

typedef struct _SESSION_INFO_502 {
  LPWSTR    sesi502_cname;
  LPWSTR    sesi502_username;
  DWORD     sesi502_num_opens;
  DWORD     sesi502_time;
  DWORD     sesi502_idle_time;
  DWORD     sesi502_user_flags;
  LPWSTR    sesi502_cltype_name;
  LPWSTR    sesi502_transport;
} SESSION_INFO_502, *PSESSION_INFO_502, *LPSESSION_INFO_502;

Members

sesi502_cname
Pointer to a Unicode string specifying the name of the computer that established the session.
sesi502_username
Pointer to a Unicode string specifying the name of the user who established the session.
sesi502_num_opens
Specifies the number of files, devices, and pipes opened during the session.
sesi502_time
Specifies the number of seconds the session has been active.
sesi502_idle_time
Specifies the number of seconds the session has been idle.
sesi502_user_flags
Specifies a value that describes how the user established the session. This member can be one of the following values.
Value | Meaning
SESS_GUEST | The user specified by the sesi502_username member established the session using a guest account.
SESS_NOENCRYPTION | The user specified by the sesi502_username member established the session without using password encryption.

sesi502_cltype_name
Pointer to a Unicode string that specifies the type of client that established the session. Following are the defined types for LAN Manager servers.
Value | Meaning
DOS LM 1.0 | LAN Manager for MS-DOS 1.0 clients.
DOS LM 2.0 | LAN Manager for MS-DOS 2.0 clients.
OS/2 LM 1.0 | LAN Manager for MS-OS/2 1.0 clients.
OS/2 LM 2.0 | LAN Manager for MS-OS/2 2.0 clients.

Sessions from LAN Manager servers running UNIX also will appear as LAN Manager 2.0.

sesi502_transport
Specifies the name of the transport that the client is using to communicate with the server.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Session Functions, NetSessionEnum


SHARE_INFO_0

The SHARE_INFO_0 structure contains the name of the shared resource.

typedef struct _SHARE_INFO_0 {
  LPWSTR    shi0_netname;
} SHARE_INFO_0, *PSHARE_INFO_0, *LPSHARE_INFO_0;

Members

shi0_netname
Pointer to a Unicode string specifying the share name of a resource.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareEnum, NetShareGetInfo


SHARE_INFO_1

The SHARE_INFO_1 structure contains information about the shared resource, including the name and type of the resource, and a comment associated with the resource.

typedef struct _SHARE_INFO_1 {
  LPWSTR    shi1_netname;
  DWORD     shi1_type;
  LPWSTR    shi1_remark;
} SHARE_INFO_1, *PSHARE_INFO_1, *LPSHARE_INFO_1;

Members

shi1_netname
Pointer to a Unicode string specifying the share name of a resource. Calls to the NetShareSetInfo function ignore this member.
shi1_type
Specifies a DWORD value that contains the type of the shared resource. Calls to the NetShareSetInfo function ignore this member.
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)
STYPE_SPECIAL | Special share reserved for interprocess communication (IPC$) or remote administration of the server (ADMIN$). Can also refer to administrative shares such as C$, D$, E$, and so forth. For more information, see the network management share functions.

shi1_remark
Pointer to a Unicode string specifying an optional comment about the shared resource.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareEnum, NetShareGetInfo, NetShareSetInfo


share_info_1

Windows 95/98/Me: The share_info_1 structure contains information about the shared resource, including the name and type of the resource, and a comment associated with the resource.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000. You can use the SHARE_INFO_1 structure instead.

struct _share_info_1 {
  char            shi1_netname[LM20_NNLEN+1];
  char            shi1_pad1;
  unsigned short  shi1_type;
  char FAR *      shi1_remark;
};

Members

shi1_netname
Specifies a string containing the share name of the resource.
shi1_pad1
Specifies padding inserted to align the next member.
shi1_type
Specifies an unsigned SHORT integer that contains the type of the shared resource.
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)
STYPE_SPECIAL | Special share reserved for interprocess communication (IPC$) or remote administration of the server (ADMIN$). Can also refer to administrative shares such as C$, D$, E$, and so forth. For more information, see the network management share functions.

shi1_remark
Pointer to a string containing an optional comment about the shared resource.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareEnum, share_info_50


SHARE_INFO_2

The SHARE_INFO_2 structure contains information about the shared resource, including name of the resource, type and permissions, and the number of current connections.

typedef struct _SHARE_INFO_2 {
  LPWSTR    shi2_netname;
  DWORD     shi2_type;
  LPWSTR    shi2_remark;
  DWORD     shi2_permissions;
  DWORD     shi2_max_uses;
  DWORD     shi2_current_uses;
  LPWSTR    shi2_path;
  LPWSTR    shi2_passwd;
} SHARE_INFO_2, *PSHARE_INFO_2, *LPSHARE_INFO_2;

Members

shi2_netname
Pointer to a Unicode string specifying the share name of a resource. Calls to the NetShareSetInfo function ignore this member.
shi2_type
Specifies a DWORD value that contains the type of the shared resource. Calls to the NetShareSetInfo function ignore this member.
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)
STYPE_SPECIAL | Special share reserved for interprocess communication (IPC$) or remote administration of the server (ADMIN$). Can also refer to administrative shares such as C$, D$, E$, and so forth. For more information, see the network management share functions.

shi2_remark
Pointer to a Unicode string that contains an optional comment about the shared resource.
shi2_permissions
Specifies a DWORD value that indicates the shared resource's permissions for servers running with share-level security. A server running user-level security ignores this member. This member can be one or more of the following values. Calls to the NetShareSetInfo function ignore this member.
Value | Meaning
ACCESS_READ | Permission to read data from a resource and, by default, to execute the resource.
ACCESS_WRITE | Permission to write data to the resource.
ACCESS_CREATE | Permission to create an instance of the resource (such as a file); data can be written to the resource as the resource is created.
ACCESS_EXEC | Permission to execute the resource.
ACCESS_DELETE | Permission to delete the resource.
ACCESS_ATRIB | Permission to modify the resource's attributes (such as the date and time when a file was last modified).
ACCESS_PERM | Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user or application.
ACCESS_ALL | Permission to read, write, create, execute, and delete resources, and to modify their attributes and permissions.

shi2_max_uses
Specifies a DWORD value that indicates the maximum number of concurrent connections that the shared resource can accommodate. The number of connections is unlimited if the value specified in shi2_max_uses is –1.
shi2_current_uses
Specifies a DWORD value that indicates the number of current connections to the resource. Calls to the NetShareSetInfo function ignore this member.
shi2_path
Pointer to a Unicode string specifying the local path for the shared resource. For disks, shi2_path is the path being shared. For print queues, shi2_path is the name of the print queue being shared. Calls to the NetShareSetInfo function ignore this member.
shi2_passwd
Pointer to a Unicode string that specifies the share's password when the server is running with share-level security. If the server is running with user-level security, shi2_passwd is ignored. The shi2_passwd member can be no longer than SHPWLEN+1 bytes (including a terminating null character). Calls to the NetShareSetInfo function ignore this member.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareAdd, NetShareEnum, NetShareGetInfo, NetShareSetInfo


share_info_50

Windows 95/98/Me: The share_info_50 structure contains information about the shared resource, including the name and type of the resource, a comment associated with the resource, and passwords.

Windows NT/2000 or later: This structure is not supported on Windows NT/Windows 2000.

struct _share_info_50 {
  char            shi50_netname[LM20_NNLEN+1];
  unsigned char   shi50_type;
  unsigned short  shi50_flags;
  char FAR *      shi50_remark;
  char FAR *      shi50_path;
  char            shi50_rw_password[SHPWLEN+1];
  char            shi50_ro_password[SHPWLEN+1];
};

Members

shi50_netname
Specifies a string containing the share name of the resource.
shi50_type
Specifies the type of resource share. This member can be one of the following predefined values.
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)
STYPE_SPECIAL | Special share reserved for interprocess communication (IPC$) or remote administration of the server (ADMIN$). Can also refer to administrative shares such as C$, D$, E$, and so forth. For more information, see the network management share functions.

shi50_flags
Specifies an unsigned SHORT integer describing the resource, when the server is running with share-level security. This member can be one or more of the following values.
Value | Meaning
SHI50F_RDONLY | The share can be opened with read-only access.
SHI50F_FULL | The share can be opened with read/write access.
SHI50F_ACCESSMASK | The share can be opened with read/write access.
SHI50F_PERSIST | The share is restored at system startup.
SHI50F_SYSTEM | The share is a hidden share, and normally is not visible.

In a user-level security environment, specify the value SHI50F_FULL. When the server is running with user-level security the network management access functions (those that begin with NetAccess) determine the access rights.

shi50_remark
Pointer to a string containing an optional comment about the shared resource.
shi50_path
Pointer to a string specifying the local path for the shared resource. Note that the string specified must contain only uppercase characters. If the path contains lowercase characters, calls to the NetShareAdd and NetShareSetInfo functions can fail with NERR_UnknownDevDir or ERROR_BAD_NET_NAME.
shi50_rw_password
Specifies a string containing the password (when the server is running with share-level security) required to read data from and write data to the resource, and to execute the resource. If the server is running with user-level security, this member is ignored.
shi50_ro_password
Specifies a string containing the password (when the server is running with share-level security) required to read data from the resource and, by default, to execute the resource. If the server is running with user-level security, this member is ignored.

Requirements

Windows NT/2000 or later: Unsupported .
Windows 95/98/Me: Requires Windows 95 or later.
Header: Declared in Svrapi.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareAdd, NetShareEnum, NetShareGetInfo, NetShareSetInfo, share_info_1


SHARE_INFO_501

The SHARE_INFO_501 structure contains information about the shared resource including the name and type of the resource, and a comment associated with the resource.

typedef struct _SHARE_INFO_501 {
  LPWSTR    shi501_netname;
  DWORD     shi501_type;
  LPWSTR    shi501_remark;
  DWORD     shi501_flags;
} SHARE_INFO_501, *PSHARE_INFO_501, *LPSHARE_INFO_501;

Members

shi501_netname
Pointer to a Unicode string specifying the name of a shared resource.
shi501_type
Specifies a DWORD value that indicates the type of share.
Value | Meaning
STYPE_DISKTREE | Disk drive
STYPE_PRINTQ | Print queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)
STYPE_SPECIAL | Special share reserved for interprocess communication (IPC$) or remote administration of the server (ADMIN$). Can also refer to administrative shares such as C$, D$, E$, and so forth. For more information, see the network management share functions.

shi501_remark
Pointer to a Unicode string specifying an optional comment about the shared resource.
shi501_flags
Reserved; must be zero.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareGetInfo


SHARE_INFO_502

The SHARE_INFO_502 structure contains information about the shared resource, including name of the resource, type and permissions, number of connections, and other pertinent information.

typedef struct _SHARE_INFO_502 {
  LPWSTR    shi502_netname;
  DWORD     shi502_type;
  LPWSTR    shi502_remark;
  DWORD     shi502_permissions;
  DWORD     shi502_max_uses;
  DWORD     shi502_current_uses;
  LPWSTR    shi502_path;
  LPWSTR    shi502_passwd;
  DWORD     shi502_reserved;
  PSECURITY_DESCRIPTOR  shi502_security_descriptor;
} SHARE_INFO_502, *PSHARE_INFO_502, *LPSHARE_INFO_502;

Members

shi502_netname
Pointer to a Unicode string specifying the name of a shared resource. Calls to the NetShareSetInfo function ignore this member.
shi502_type
Specifies a DWORD value that indicates the type of share. Calls to the NetShareSetInfo function ignore this member.
Value | Meaning
STYPE_DISKTREE | Disk Drive
STYPE_PRINTQ | Print Queue
STYPE_DEVICE | Communication device
STYPE_IPC | Interprocess communication (IPC)
STYPE_SPECIAL | Special share reserved for interprocess communication (IPC$) or remote administration of the server (ADMIN$). Can also refer to administrative shares such as C$, D$, E$, and so forth. For more information, see the network management share functions.

shi502_remark
Pointer to a Unicode string specifying an optional comment about the shared resource.
shi502_permissions
Specifies a DWORD value that indicates the shared resource's permissions for servers running with share-level security. This member is ignored on a server running user-level security. This member can be any of the following values. Calls to the NetShareSetInfo function ignore this member.
Value | Meaning
ACCESS_READ | Permission to read data from a resource and, by default, to execute the resource.
ACCESS_WRITE | Permission to write data to the resource.
ACCESS_CREATE | Permission to create an instance of the resource (such as a file); data can be written to the resource as the resource is created.
ACCESS_EXEC | Permission to execute the resource.
ACCESS_DELETE | Permission to delete the resource.
ACCESS_ATRIB | Permission to modify the resource's attributes (such as the date and time when a file was last modified).
ACCESS_PERM | Permission to modify the permissions (read, write, create, execute, and delete) assigned to a resource for a user or application.
ACCESS_ALL | Permission to read, write, create, execute, and delete resources, and to modify their attributes and permissions.

shi502_max_uses
Specifies a DWORD value that indicates the maximum number of concurrent connections that the shared resource can accommodate. The number of connections is unlimited if the value specified in shi502_max_uses is –1.
shi502_current_uses
Specifies a DWORD value that indicates the number of current connections to the resource. Calls to the NetShareSetInfo function ignore this member.
shi502_path
Pointer to a Unicode string that contains the local path for the shared resource. For disks, shi502_path is the path being shared. For print queues, shi502_path is the name of the print queue being shared. Calls to the NetShareSetInfo function ignore this member.
shi502_passwd
Pointer to a Unicode string that specifies the share's password (when the server is running with share-level security). If the server is running with user-level security, shi502_passwd is ignored. The shi502_passwd member can be no longer than SHPWLEN+1 bytes (including a terminating null character). Calls to the NetShareSetInfo function ignore this member.
shi502_reserved
Reserved; must be zero. Calls to the NetShareSetInfo function ignore this member.
shi502_security_descriptor
Specifies the security descriptor associated with this share.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareAdd, NetShareEnum, NetShareGetInfo, NetShareSetInfo


SHARE_INFO_1004

The SHARE_INFO_1004 structure contains a comment associated with the shared resource.

typedef struct _SHARE_INFO_1004 {
  LPWSTR    shi1004_remark;
} SHARE_INFO_1004, *PSHARE_INFO_1004, *LPSHARE_INFO_1004;

Members

shi1004_remark
Pointer to a Unicode string that contains an optional comment about the shared resource.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareSetInfo


SHARE_INFO_1005

The SHARE_INFO_1005 structure contains information about the shared resource.

typedef struct _SHARE_INFO_1005 {
  DWORD    shi1005_flags;
} SHARE_INFO_1005, *PSHARE_INFO_1005, *LPSHARE_INFO_1005;

Members

shi1005_flags
Specifies a DWORD value that can contain the following value.
Value | Meaning
SHI1005_FLAGS_DFS_ROOT | The specified share is the root volume in a Dfs tree structure.

Remarks

This flag can be retrieved by calling the NetShareGetInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareGetInfo


SHARE_INFO_1006

The SHARE_INFO_1006 structure specifies the maximum number of concurrent connections that the shared resource can accommodate.

typedef struct _SHARE_INFO_1006 {
  DWORD    shi1006_max_uses;
} SHARE_INFO_1006, *PSHARE_INFO_1006, *LPSHARE_INFO_1006;

Members

shi1006_max_uses
Specifies a DWORD value that indicates the maximum number of concurrent connections that the shared resource can accommodate. The number of connections is unlimited if the value specified in shi1006_max_uses is –1.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareSetInfo


SHARE_INFO_1501

The SHARE_INFO_1501 structure contains the security descriptor associated with the specified share.

typedef struct _SHARE_INFO_1501 {
  DWORD    shi1501_reserved;
  PSECURITY_DESCRIPTOR    shi1501_security_descriptor;
} SHARE_INFO_1501, *PSHARE_INFO_1501, *LPSHARE_INFO_1501;

Members

shi1501_reserved
Reserved; must be zero.
shi1501_security_descriptor
Specifies the security descriptor associated with the share.

Requirements

Windows NT/2000 or later: Requires Windows 2000 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmshare.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Share Functions, NetShareSetInfo


STAT_SERVER_0

The STAT_SERVER_0 structure contains statistical information about the server.

typedef struct _STAT_SERVER_0 {
  DWORD          sts0_start;
  DWORD          sts0_fopens;
  DWORD          sts0_devopens;
  DWORD          sts0_jobsqueued;
  DWORD          sts0_sopens;
  DWORD          sts0_stimedout;
  DWORD          sts0_serrorout;
  DWORD          sts0_pwerrors;
  DWORD          sts0_permerrors;
  DWORD          sts0_syserrors;
  DWORD          sts0_bytessent_low;
  DWORD          sts0_bytessent_high;
  DWORD          sts0_bytesrcvd_low;
  DWORD          sts0_bytesrcvd_high;
  DWORD          sts0_avresponse;
  DWORD          sts0_reqbufneed;
  DWORD          sts0_bigbufneed;
} STAT_SERVER_0, *PSTAT_SERVER_0, *LPSTAT_SERVER_0;

Members

sts0_start
Specifies a DWORD value that indicates the time when statistics collection started (or when the statistics were last cleared). The value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. To calculate the length of time that statistics have been collected, subtract the value of this member from the present time.
sts0_fopens
Specifies a DWORD value that indicates the number of times a file is opened on a server. This includes the number of times named pipes are opened.
sts0_devopens
Specifies a DWORD value that indicates the number of times a server device is opened.
sts0_jobsqueued
Specifies a DWORD value that indicates the number of server print jobs spooled.
sts0_sopens
Specifies a DWORD value that indicates the number of times the server session started.
sts0_stimedout
Specifies a DWORD value that indicates the number of times the server session automatically disconnected.
sts0_serrorout
Specifies a DWORD value that indicates the number of times the server sessions failed with an error.
sts0_pwerrors
Specifies a DWORD value that indicates the number of server password violations.
sts0_permerrors
Specifies a DWORD value that indicates the number of server access permission errors.
sts0_syserrors
Specifies a DWORD value that indicates the number of server system errors.
sts0_bytessent_low
Specifies the low-order DWORD of the number of server bytes sent to the network.
sts0_bytessent_high
Specifies the high-order DWORD of the number of server bytes sent to the network.
sts0_bytesrcvd_low
Specifies the low-order DWORD of the number of server bytes received from the network.
sts0_bytesrcvd_high
Specifies the high-order DWORD of the number of server bytes received from the network.
sts0_avresponse
Specifies a DWORD value that indicates the average server response time (in milliseconds).
sts0_reqbufneed
Specifies a DWORD value that indicates the number of times the server required a request buffer but failed to allocate one. This value indicates that the server parameters may need adjustment.
sts0_bigbufneed
Specifies a DWORD value that indicates the number of times the server required a big buffer but failed to allocate one. This value indicates that the server parameters may need adjustment.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmstats.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Statistics Functions, NetStatisticsGet


STAT_WORKSTATION_0

The STAT_WORKSTATION_0 structure contains statistical information about the specified workstation.

typedef struct _STAT_WORKSTATION_0 {
  LARGE_INTEGER   StatisticsStartTime;

  LARGE_INTEGER   BytesReceived;
  LARGE_INTEGER   SmbsReceived;
  LARGE_INTEGER   PagingReadBytesRequested;
  LARGE_INTEGER   NonPagingReadBytesRequested;
  LARGE_INTEGER   CacheReadBytesRequested;
  LARGE_INTEGER   NetworkReadBytesRequested;

  LARGE_INTEGER   BytesTransmitted;
  LARGE_INTEGER   SmbsTransmitted;
  LARGE_INTEGER   PagingWriteBytesRequested;
  LARGE_INTEGER   NonPagingWriteBytesRequested;
  LARGE_INTEGER   CacheWriteBytesRequested;
  LARGE_INTEGER   NetworkWriteBytesRequested;

  DWORD           InitiallyFailedOperations;
  DWORD           FailedCompletionOperations;

  DWORD           ReadOperations;
  DWORD           RandomReadOperations;
  DWORD           ReadSmbs;
  DWORD           LargeReadSmbs;
  DWORD           SmallReadSmbs;

  DWORD           WriteOperations;
  DWORD           RandomWriteOperations;
  DWORD           WriteSmbs;
  DWORD           LargeWriteSmbs;
  DWORD           SmallWriteSmbs;

  DWORD           RawReadsDenied;
  DWORD           RawWritesDenied;

  DWORD           NetworkErrors;

  //  Connection/Session counts
  DWORD           Sessions;
  DWORD           FailedSessions;
  DWORD           Reconnects;
  DWORD           CoreConnects;
  DWORD           Lanman20Connects;
  DWORD           Lanman21Connects;
  DWORD           LanmanNtConnects;
  DWORD           ServerDisconnects;
  DWORD           HungSessions;
  DWORD           UseCount;
  DWORD           FailedUseCount;

  DWORD           CurrentCommands;

} STAT_WORKSTATION_0, *PSTAT_WORKSTATION_0, *LPSTAT_WORKSTATION_0;

Members

StatisticsStartTime
Specifies the time statistics collection started. This member also indicates when statistics for the workstations were last cleared. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970.
BytesReceived
Specifies the total number of bytes received by the workstation.
SmbsReceived
Specifies the total number of server message blocks (SMBs) received by the workstation.
PagingReadBytesRequested
Specifies the total number of bytes that have been read by paging I/O requests.
NonPagingReadBytesRequested
Specifies the total number of bytes that have been read by non-paging I/O requests.
CacheReadBytesRequested
Specifies the total number of bytes that have been read by cache I/O requests.
NetworkReadBytesRequested
Specifies the total amount of bytes that have been read by disk I/O requests.
BytesTransmitted
Specifies the total number of bytes transmitted by the workstation.
SmbsTransmitted
Specifies the total number of SMBs transmitted by the workstation.
PagingWriteBytesRequested
Specifies the total number of bytes that have been written by paging I/O requests.
NonPagingWriteBytesRequested
Specifies the total number of bytes that have been written by non-paging I/O requests.
CacheWriteBytesRequested
Specifies the total number of bytes that have been written by cache I/O requests.
NetworkWriteBytesRequested
Specifies the total number of bytes that have been written by disk I/O requests.
InitiallyFailedOperations
Specifies the total number of network operations that failed to begin.
FailedCompletionOperations
Specifies the total number of network operations that failed to complete.
ReadOperations
Specifies the total number of read operations initiated by the workstation.
RandomReadOperations
Specifies the total number of random access reads initiated by the workstation.
ReadSmbs
Specifies the total number of read requests the workstation has sent to servers.
LargeReadSmbs
Specifies the total number of read requests the workstation has sent to servers that are greater than twice the size of the server's negotiated buffer size.
SmallReadSmbs
Specifies the total number of read requests the workstation has sent to servers that are less than 1/4 of the size of the server's negotiated buffer size.
WriteOperations
Specifies the total number of write operations initiated by the workstation.
RandomWriteOperations
Specifies the total number of random access writes initiated by the workstation.
WriteSmbs
Specifies the total number of write requests the workstation has sent to servers.
LargeWriteSmbs
Specifies the total number of write requests the workstation has sent to servers that are greater than twice the size of the server's negotiated buffer size.
SmallWriteSmbs
Specifies the total number of write requests the workstation has sent to servers that are less than 1/4 of the size of the server's negotiated buffer size.
RawReadsDenied
Specifies the total number of raw read requests made by the workstation that have been denied. This member is not used on Windows 2000.
RawWritesDenied
Specifies the total number of raw write requests made by the workstation that have been denied. This member is not used on Windows 2000.
NetworkErrors
Specifies the total number of network errors received by the workstation.
Sessions
Specifies the total number of workstation sessions that were established.
FailedSessions
Specifies the number of times the workstation attempted to create a session but failed.
Reconnects
Specifies the total number of connections that have failed.
CoreConnects
Specifies the total number of connections to servers supporting the PCNET dialect that have succeeded.
Lanman20Connects
Specifies the total number of connections to servers supporting the LanManager 2.0 dialect that have succeeded.
Lanman21Connects
Specifies the total number of connections to servers supporting the LanManager 2.1 dialect that have succeeded.
LanmanNtConnects
Specifies the total number of connections to servers supporting the Windows NT dialect that have succeeded.
ServerDisconnects
Specifies the number of times the workstation was disconnected by a network server.
HungSessions
Specifies the total number of sessions that have expired on the workstation.
UseCount
Specifies the total number of network connections established by the workstation.
FailedUseCount
Specifies the total number of failed network connections for the workstation.
CurrentCommands
Specifies the number of current requests that have not been completed.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmstats.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Statistics Functions, NetStatisticsGet


STD_ALERT

The STD_ALERT structure contains the time and date when a significant event occurred. The structure also contains an alert class and the name of the application that is raising the alert message. You must specify the STD_ALERT structure when you send an alert message using the NetAlertRaise function.

typedef struct _STD_ALERT {
  DWORD  alrt_timestamp;
  WCHAR  alrt_eventname[EVLEN + 1];
  WCHAR  alrt_servicename[SNLEN + 1];
}STD_ALERT, *PSTD_ALERT, *LPSTD_ALERT;

Members

alrt_timestamp
Specifies the time and date of the event. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT.
alrt_eventname
Specifies a Unicode string indicating the alert class (type of event). This parameter can be one of the following predefined values, or another alert class that you have defined for network applications. (The event name for an alert can be any text string.)
Name | Meaning
ALERT_ADMIN_EVENT | An administrator's intervention is required.
ALERT_ERRORLOG_EVENT | An entry was added to the error log.
ALERT_MESSAGE_EVENT | A user or application received a broadcast message.
ALERT_PRINT_EVENT | A print job completed or a print error occurred.
ALERT_USER_EVENT | An application or resource was used.

alrt_servicename
Specifies a Unicode string indicating the service application that is raising the alert message.

Remarks

The STD_ALERT structure must be followed by one ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, or USER_OTHER_INFO structure. These structures can optionally be followed by variable-length data. The calling application must allocate the memory for all structures and variable-length data in an alert message buffer.

See NetAlertRaise for a code sample that raises an administrative alert using a STD_ALERT structure and an ADMIN_OTHER_INFO structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Alert Functions, ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, USER_OTHER_INFO, NetAlertRaise


TIME_OF_DAY_INFO

The TIME_OF_DAY_INFO structure contains information about the time of day from a remote server.

typedef struct _TIME_OF_DAY_INFO {
  DWORD      tod_elapsedt;
  DWORD      tod_msecs;
  DWORD      tod_hours;
  DWORD      tod_mins;
  DWORD      tod_secs;
  DWORD      tod_hunds;
  LONG       tod_timezone;
  DWORD      tod_tinterval;
  DWORD      tod_day;
  DWORD      tod_month;
  DWORD      tod_year;
  DWORD      tod_weekday;
} TIME_OF_DAY_INFO, *PTIME_OF_DAY_INFO, *LPTIME_OF_DAY_INFO;

Members

tod_elapsedt
Specifies a DWORD value that contains the number of seconds since 00:00:00, January 1, 1970, GMT.
tod_msecs
Specifies a DWORD value that contains the number of milliseconds from an arbitrary starting point (system reset).

Typically, this member is read twice, once when the process begins and again at the end. To determine the elapsed time between the process's start and finish, you can subtract the first value from the second.

tod_hours
Specifies a DWORD value that contains the current hour. Valid values are 0 through 23.
tod_mins
Specifies a DWORD value that contains the current minute. Valid values are 0 through 59.
tod_secs
Specifies a DWORD value that contains the current second. Valid values are 0 through 59.
tod_hunds
Specifies a DWORD value that contains the current hundredth second (0.01 second). Valid values are 0 through 99.
tod_timezone
Specifies the time zone of the server. This value is calculated, in minutes, from Greenwich Mean Time (GMT). For time zones west of Greenwich, the value is positive; for time zones east of Greenwich, the value is negative. A value of –1 indicates that the time zone is undefined.
tod_tinterval
Specifies a DWORD value that contains the time interval for each tick of the clock. Each integral integer represents one ten-thousandth second (0.0001 second).
tod_day
Specifies a DWORD value that contains the day of the month. Valid values are 1 through 31.
tod_month
Specifies a DWORD value that contains the month of the year. Valid values are 1 through 12.
tod_year
Specifies a DWORD value that contains the year.
tod_weekday
Specifies a DWORD value that contains the day of the week. Valid values are 0 through 6, where 0 is Sunday, 1 is Monday, and so on.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmremutl.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Remote Utility functions, NetRemoteTOD


USE_INFO_0

The USE_INFO_0 structure contains the name of a shared resource and the local device redirected to it.

typedef struct _USE_INFO_0 {
  LPWSTR  ui0_local;
  LPWSTR  ui0_remote;
}USE_INFO_0, *PUSE_INFO_0, *LPUSE_INFO_0;

Members

ui0_local
Pointer to a Unicode string that specifies the local device name (for example, drive E or LPT1) being redirected to the shared resource. The constant DEVLEN specifies the maximum number of characters in the string.
ui0_remote
Pointer to a Unicode string that specifies the share name of the remote resource being accessed. The string is in the form:
\\servername\sharename

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmuse.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Use Functions, NetUseEnum, NetUseGetInfo


USE_INFO_1

The USE_INFO_1 structure contains information about the connection between a local device and a shared resource. The information includes connection status and connection type.

typedef struct _USE_INFO_1 {
  LPWSTR  ui1_local;
  LPWSTR  ui1_remote;
  LPWSTR  ui1_password;
  DWORD   ui1_status;
  DWORD   ui1_asg_type;
  DWORD   ui1_refcount;
  DWORD   ui1_usecount;
}USE_INFO_1, *PUSE_INFO_1, *LPUSE_INFO_1;

Members

ui1_local
Pointer to a Unicode string that specifies the local device name (for example, drive E or LPT1) being redirected to the shared resource. The constant DEVLEN specifies the maximum number of characters in the string. This member can be NULL. For more information, see the following Remarks section.
ui1_remote
Pointer to a Unicode string that specifies the share name of the remote resource being accessed. The string is in the form:
\\servername\sharename
ui1_password
Pointer to a Unicode string that contains the password needed to establish a session between a specific workstation and a server.
ui1_status
Specifies the status of the connection. This element is not used by the NetUseAdd function. The following values are defined.
Value | Meaning
USE_OK | The connection is valid.
USE_PAUSED | Paused by local workstation.
USE_SESSLOST | Disconnected.
USE_DISCONN | An error occurred.
USE_NETERR | A network error occurred.
USE_CONN | The connection is being made.
USE_RECONN | Reconnecting.

ui1_asg_type
Specifies the type of remote resource being accessed. This member can be one of the following values.
Value | Meaning
USE_WILDCARD | Matches the type of the server's shared resources. Wildcards can be used only with the NetUseAdd function, and only when the ui1_local member is a null string. For more information, see the following Remarks section.
USE_DISKDEV | Disk device.
USE_SPOOLDEV | Spooled printer.
USE_IPC | Interprocess communication (IPC).

ui1_refcount
Specifies how many files, directories, and other processes are open on the remote resource. This element is not used by the NetUseAdd function.
ui1_usecount
Specifies how many explicit connections (redirection with a local device name) or implicit UNC connections (redirection without a local device name) are established with the resource.

Remarks

Specifying a NULL ui1_local member requests authentication with the server without redirecting a drive letter or a device. Future redirections involving the server while the same connection is in effect use the password specified by the ui1_password member in the initial call to the NetUseAdd function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmuse.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Use Functions, NetUseAdd, NetUseEnum, NetUseGetInfo


USE_INFO_2

The USE_INFO_2 structure contains information about a connection between a local computer and a shared resource, including connection type, connection status, user name, and domain name.

typedef struct _USE_INFO_2 {
  LPWSTR   ui2_local;
  LPWSTR   ui2_remote;
  LPWSTR   ui2_password;
  DWORD    ui2_status;
  DWORD    ui2_asg_type;
  DWORD    ui2_refcount;
  DWORD    ui2_usecount;
  LPWSTR   ui2_username;
  LPWSTR   ui2_domainname;
}USE_INFO_2, *PUSE_INFO_2, *LPUSE_INFO_2;

Members

ui2_local
Pointer to a Unicode string that contains the local device name (for example, drive E or LPT1) being redirected to the shared resource. The constant DEVLEN specifies the maximum number of characters in the string. This member can be NULL. For more information, see the following Remarks section.
ui2_remote
Pointer to a Unicode string that specifies the share name of the remote resource. The string is in the form
\\servername\sharename
ui2_password
Pointer to a Unicode string that contains the password needed to establish a session with a specific workstation.
ui2_status
Specifies the status of the connection. This element is not used by the NetUseAdd function. The following values are defined.
Value | Meaning
USE_OK | The connection is successful.
USE_PAUSED | Paused by a local workstation.
USE_SESSLOST | Disconnected.
USE_DISCONN | An error occurred.
USE_NETERR | A network error occurred.
USE_CONN | The connection is being made.
SE_RECONN | Reconnecting.

ui2_asg_type
Specifies the type of remote resource being accessed. This member can be one of the following values.
Value | Meaning
USE_WILDCARD | Matches the type of the server's shared resources. Wildcards can be used only with the NetUseAdd function, and only when the ui2_local member is a null string. For more information, see the following Remarks section.
USE_DISKDEV | Disk device.
USE_SPOOLDEV | Spooled printer.
USE_IPC | Interprocess communication (IPC).

ui2_refcount
Specifies the number of files, directories, and other processes that are open on the remote resource. This element is not used by the NetUseAdd function.
ui2_usecount
Specifies the number of explicit connections (redirection with a local device name) or implicit UNC connections (redirection without a local device name) that are established with the resource.
ui2_username
Pointer to the name of the user who initiated the connection.
ui2_domainname
Pointer to the domain name of the remote resource.

Remarks

Specifying a NULL ui2_local member requests authentication with the server without redirecting a drive letter or a device. Future redirections involving the server while the same connection is in effect use the authentication information specified in the initial call to the NetUseAdd function. This information includes the combination of the ui2_password, ui2_username, and ui2_domainname members.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmuse.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Use Functions, NetUseAdd, NetUseEnum, NetUseGetInfo


USER_INFO_0

The USER_INFO_0 structure contains a user account name.

typedef struct _USER_INFO_0 {
  LPWSTR    usri0_name;
}USER_INFO_0, *PUSER_INFO_0, *LPUSER_INFO_0;

Members

usri0_name
Pointer to a Unicode string that specifies the name of the user account. For the NetUserSetInfo function, this member specifies the name of the user. The number of characters in the name cannot exceed the value of UNLEN.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUseDel, NetUserEnum, NetUserSetInfo


USER_INFO_1

The USER_INFO_1 structure contains information about a user account, including account name, password data, privilege level, and the path to the user's home directory.

typedef struct _USER_INFO_1 {
  LPWSTR    usri1_name;
  LPWSTR    usri1_password;
  DWORD     usri1_password_age;
  DWORD     usri1_priv;
  LPWSTR    usri1_home_dir;
  LPWSTR    usri1_comment;
  DWORD     usri1_flags;
  LPWSTR    usri1_script_path;
}USER_INFO_1, *PUSER_INFO_1, *LPUSER_INFO_1;

Members

usri1_name
Pointer to a Unicode string that specifies the name of the user account. For the NetUserSetInfo function, this member is ignored.
usri1_password
Pointer to a Unicode string that specifies the password of the user indicated by the usri1_name member. The length cannot exceed PWLEN bytes. The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security.

By convention, Windows NT/Windows 2000 limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT/Windows 2000 server using the account.

usri1_password_age
Specifies a DWORD value that indicates the number of seconds that have elapsed since the usri1_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri1_priv
Specifies a DWORD value that indicates the level of privilege assigned to the usri1_name member. When you call the NetUserAdd function, this member must be USER_PRIV_USER. When you call the NetUserSetInfo function, this member must be the value returned by the NetUserGetInfo function or the NetUserEnum function. This member can be one of the following values.
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri1_home_dir
Pointer to a Unicode string specifying the path of the home directory for the user specified in the usri1_name member. The string can be null.
usri1_comment
Pointer to a Unicode string that contains a comment to associate with the user account. This string can be a null string, or it can have any number of characters before the terminating null character.
usri1_flags
Specifies a DWORD value that determines several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 and for Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT/Windows 2000.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. You can call the NetUserSetInfo function and clear this value to unlock a previously locked account. You cannot use this value to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT/2000 or later: The password should never expire on the account.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Windows 2000 or later: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or a Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri1_script_path
Pointer to a Unicode string specifying the path for the user's logon script file. The script file can be a .CMD file, an .EXE file, or a .BAT file. The string can also be null.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserAdd, NetUserEnum, NetUserSetInfo, NetUserGetInfo


USER_INFO_2

The USER_INFO_2 structure contains information about a user account, including the account name, password data, privilege level, the path to the user's home directory, and other user-related network statistics.

typedef struct _USER_INFO_2 {
  LPWSTR    usri2_name;
  LPWSTR    usri2_password;
  DWORD     usri2_password_age;
  DWORD     usri2_priv;
  LPWSTR    usri2_home_dir;
  LPWSTR    usri2_comment;
  DWORD     usri2_flags;
  LPWSTR    usri2_script_path;
  DWORD     usri2_auth_flags;
  LPWSTR    usri2_full_name;
  LPWSTR    usri2_usr_comment;
  LPWSTR    usri2_parms;
  LPWSTR    usri2_workstations;
  DWORD     usri2_last_logon;
  DWORD     usri2_last_logoff;
  DWORD     usri2_acct_expires;
  DWORD     usri2_max_storage;
  DWORD     usri2_units_per_week;
  PBYTE     usri2_logon_hours;
  DWORD     usri2_bad_pw_count;
  DWORD     usri2_num_logons;
  LPWSTR    usri2_logon_server;
  DWORD     usri2_country_code;
  DWORD     usri2_code_page;
}USER_INFO_2, *PUSER_INFO_2, *LPUSER_INFO_2;

Members

usri2_name
Pointer to a Unicode string that specifies the name of the user account. Calls to the NetUserSetInfo function ignore this member. The number of characters in the name cannot exceed the value of UNLEN.
usri2_password
Pointer to a Unicode string that specifies the password for the user identified by the usri2_name member. The length cannot exceed PWLEN bytes. The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security.

By convention, Windows NT/Windows 2000 limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT/Windows 2000 server using the account.

usri2_password_age
Specifies a DWORD value that indicates the number of seconds that have elapsed since the usri2_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri2_priv
Specifies a DWORD value that indicates the level of privilege assigned to the usri2_name member. For calls to the NetUserAdd function, this member must be USER_PRIV_USER. For the NetUserSetInfo function, this member must be the value returned by the NetUserGetInfo function or the NetUserEnum function. This member can be one of the following values.
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri2_home_dir
Pointer to a Unicode string specifying the path of the home directory for the user specified by the usri2_name member. The string can be null.
usri2_comment
Pointer to a Unicode string that contains a comment to associate with the user account. The string can be a null string, or it can have any number of characters before the terminating null character.
usri2_flags
Specifies a DWORD value that determines several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 and Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT/Windows 2000.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. You can call the NetUserSetInfo function to clear this value and unlock a previously locked account. You cannot use this value to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT/2000 or later: The password should never expire on the account.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Windows 2000 or later: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri2_script_path
Pointer to a Unicode string specifying the path for the user's logon script file. The script file can be a .CMD file, an .EXE file, or a .BAT file. The string can also be null.
usri2_auth_flags
Specifies a DWORD value that contains a set of bit flags defining the user's operator privileges.

Calls to the NetUserGetInfo and NetUserEnum functions return a value based on the user's local group membership. If the user is a member of Print Operators, AF_OP_PRINT is set. If the user is a member of Server Operators, AF_OP_SERVER is set. If the user is a member of the Account Operators, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

Windows NT/2000 or later: The following restrictions apply:

  • When you call the NetUserAdd function, this member must be zero.
  • When you call the NetUserSetInfo function, this member must be the value returned from a call to NetUserGetInfo or to NetUserEnum.

This member can be one or more of the following values.
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri2_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri2_usr_comment
Pointer to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri2_parms
Pointer to a Unicode string that is reserved for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri2_workstations
Pointer to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas. A null string indicates that there is no restriction. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri2_flags member.
usri2_last_logon
Specifies a DWORD value that indicates when the last logon occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. This member is ignored by the NetUserAdd and NetUserSetInfo functions.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logon occurred at the time indicated by the largest retrieved value.

usri2_last_logoff
Specifies a DWORD value that indicates when the last logoff occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. A value of zero indicates that the last logoff time is unknown.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logoff occurred at the time indicated by the largest retrieved value.

usri2_acct_expires
Specifies a DWORD value that indicates when the account expires. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970, GMT. A value of TIMEQ_FOREVER indicates that the account never expires.
usri2_max_storage
Specifies a DWORD value that indicates the maximum amount of disk space the user can use. Specify USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri2_units_per_week
Specifies a DWORD value that indicates the number of equal-length time units into which the week is divided. This value is required to compute the length of the bit string in the usri2_logon_hours member.

This value must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored by the NetUserAdd and NetUserSetInfo functions.

Windows NT/2000 or later: For Windows NT/Windows 2000 services, the units must be one of the following values: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.

usri2_logon_hours
Pointer to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, in Greenwich Mean Time (GMT).

The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus 8 hours for Pacific Standard Time).

Specify a null pointer in this member when calling the NetUserAdd function to indicate no time restriction. Specify a null pointer when calling the NetUserSetInfo function to indicate that no change is to be made to the times during which the user can log on.

usri2_bad_pw_count
Specifies a DWORD value that indicates the number of times the user tried to log on to the account using an incorrect password. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is replicated from the primary domain controller (PDC); it is also maintained on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user tried to log on using an incorrect password is the largest value retrieved.

usri2_num_logons
Specifies a DWORD value that indicates the number of times the user logged on successfully to this account. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user logged on successfully is the sum of the retrieved values.

usri2_logon_server
Pointer to a Unicode string that contains the name of the server to which logon requests are sent. Server names should be preceded by two backslashes (\\). To indicate that the logon request can be handled by any logon server, specify an asterisk (\\*) for the server name. A null string indicates that requests should be sent to the domain controller.

Windows NT/2000 or later: For Windows NT/Windows 2000 servers, NetUserGetInfo and NetUserEnum return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.

usri2_country_code
Specifies a DWORD value that indicates the country/region code for the user's language of choice.
usri2_code_page
Specifies a DWORD value that indicates the code page for the user's language of choice.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserAdd, NetUserEnum, NetUserSetInfo, NetUserGetInfo


USER_INFO_3

The USER_INFO_3 structure contains information about a user account, including the account name, password data, privilege level, the path to the user's home directory, relative identifiers (RIDs), and other user-related network statistics.

Whistler: On Whistler and later, it is recommended that you use the USER_INFO_4 structure instead.

This structure is valid only to Windows NT/Windows 2000 servers and not LAN Manager 2.x servers.

typedef struct _USER_INFO_3 {
  LPWSTR    usri3_name;
  LPWSTR    usri3_password;
  DWORD     usri3_password_age;
  DWORD     usri3_priv;
  LPWSTR    usri3_home_dir;
  LPWSTR    usri3_comment;
  DWORD     usri3_flags;
  LPWSTR    usri3_script_path;
  DWORD     usri3_auth_flags;
  LPWSTR    usri3_full_name;
  LPWSTR    usri3_usr_comment;
  LPWSTR    usri3_parms;
  LPWSTR    usri3_workstations;
  DWORD     usri3_last_logon;
  DWORD     usri3_last_logoff;
  DWORD     usri3_acct_expires;
  DWORD     usri3_max_storage;
  DWORD     usri3_units_per_week;
  PBYTE     usri3_logon_hours;
  DWORD     usri3_bad_pw_count;
  DWORD     usri3_num_logons;
  LPWSTR    usri3_logon_server;
  DWORD     usri3_country_code;
  DWORD     usri3_code_page;
  DWORD     usri3_user_id;
  DWORD     usri3_primary_group_id;
  LPWSTR    usri3_profile;
  LPWSTR    usri3_home_dir_drive;
  DWORD     usri3_password_expired;
}USER_INFO_3, *PUSER_INFO_3, *LPUSER_INFO_3;

Members

usri3_name
Pointer to a Unicode string that specifies the name of the user account. For the NetUserSetInfo function, this member is ignored. The number of characters in the name cannot exceed the value of UNLEN.
usri3_password
Pointer to a Unicode string that specifies the password for the user identified by the usri3_name member. The length cannot exceed PWLEN bytes. The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security.

By convention, Windows NT/Windows 2000 limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT/Windows 2000 server using the account.

usri3_password_age
Specifies a DWORD value that indicates the number of seconds that have elapsed since the usri3_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri3_priv
Specifies a DWORD value that indicates the level of privilege assigned to the usri3_name member. The NetUserAdd and NetUserSetInfo functions ignore this member. This member can be one of the following values.
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri3_home_dir
Pointer to a Unicode string specifying the path of the home directory of the user specified by the usri3_name member. The string can be null.
usri3_comment
Pointer to a Unicode string that contains a comment to associate with the user account. The string can be a null string, or it can have any number of characters before the terminating null character.
usri3_flags
Specifies a DWORD value that determines several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 and Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT/Windows 2000.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. You can call the NetUserSetInfo function to clear this value and unlock a previously locked account. You cannot use this value to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT/2000 or later: The password should never expire on the account.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Windows 2000 or later: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or a Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri3_script_path
Pointer to a Unicode string specifying the path for the user's logon script file. The script file can be a .CMD file, an .EXE file, or a .BAT file. The string can also be null.
usri3_auth_flags
Specifies a DWORD value that contains a set of bit flags defining the user's operator privileges.

For the NetUserGetInfo and NetUserEnum functions, the appropriate value is returned based on the local group membership. If the user is a member of Print Operators, AF_OP_PRINT is set. If the user is a member of Server Operators, AF_OP_SERVER is set. If the user is a member of the Account Operators, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

The NetUserAdd and NetUserSetInfo functions ignore this member.

This member can be one or more of the following values.
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri3_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri3_usr_comment
Pointer to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri3_parms
Pointer to a Unicode string that is reserved for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri3_workstations
Pointer to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas. If you do not want to restrict the number of workstations, use a null string. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri3_flags member.
usri3_last_logon
Specifies a DWORD value that indicates when the last logon occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. This member is ignored by the NetUserAdd and NetUserSetInfo functions.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logon occurred at the time indicated by the largest retrieved value.

usri3_last_logoff
Specifies a DWORD value that indicates when the last logoff occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. A value of zero indicates that the last logoff time is unknown.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logoff occurred at the time indicated by the largest retrieved value.

usri3_acct_expires
Specifies a DWORD value that indicates when the account expires. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970, GMT. A value of TIMEQ_FOREVER indicates that the account never expires.
usri3_max_storage
Specifies a DWORD value that indicates the maximum amount of disk space the user can use. Specify USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri3_units_per_week
Specifies a DWORD value that indicates the number of equal-length time units into which the week is divided. This value is required to compute the length of the bit string in the usri3_logon_hours member.

This value must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored by the NetUserAdd and NetUserSetInfo functions.

Windows NT/2000 or later: For Windows NT/Windows 2000 services, the units must be one of the following values: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.

usri3_logon_hours
Pointer to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, in Greenwich Mean Time (GMT).

The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus 8 hours for Pacific Standard Time).

Specify a null pointer in this member when calling the NetUserAdd function to indicate no time restriction. Specify a null pointer when calling the NetUserSetInfo function to indicate that no change is to be made to the times during which the user can log on.

usri3_bad_pw_count
Specifies a DWORD value that indicates the number of times the user tried to log on to the account using an incorrect password. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is replicated from the primary domain controller (PDC); it is also maintained on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user tried to log on using an incorrect password is the largest value retrieved.

usri3_num_logons
Specifies a DWORD value that indicates the number of times the user logged on successfully to this account. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user logged on successfully is the sum of the retrieved values.

usri3_logon_server
Pointer to a Unicode string that contains the name of the server to which logon requests are sent. Server names should be preceded by two backslashes (\\). To indicate that the logon request can be handled by any logon server, specify an asterisk (\\*) for the server name. A null string indicates that requests should be sent to the domain controller. For Windows NT/Windows 2000 servers, NetUserGetInfo and NetUserEnum return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri3_country_code
Specifies a DWORD value that contains the country/region code for the user's language of choice.
usri3_code_page
Specifies a DWORD value that contains the code page for the user's language of choice.
usri3_user_id
Specifies a DWORD value that contains the relative ID (RID) of the user. The RID is determined by the Security Account Manager (SAM) when the user is created. It uniquely defines the user account to SAM within the domain. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri3_primary_group_id
Specifies a DWORD value that contains the RID of the Primary Global Group for the user. When you call the NetUserAdd function, this member must be DOMAIN_GROUP_RID_USERS (defined in NTSEAPI.H). When you call NetUserSetInfo, this member must be the RID of a global group in which the user is enrolled.
usri3_profile
Pointer to a Unicode string that specifies a path to the user's profile. This value can be a null string, a local absolute path, or a UNC path.
usri3_home_dir_drive
Pointer to a Unicode string that specifies the drive letter assigned to the user's home directory for logon purposes.
usri3_password_expired
Specifies a DWORD value that contains password expiration information.

The NetUserGetInfo and NetUserEnum functions return zero if the password has not expired (and nonzero if it has).

When you call NetUserAdd or NetUserSetInfo, specify a nonzero value in this member to inform users that they must change their password at the next logon. To turn off this message, call NetUserSetInfo and specify zero in this member. Note that you cannot specify zero to negate the expiration of a password that has already expired.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserAdd, NetUserEnum, NetUserSetInfo, NetUserGetInfo


USER_INFO_4

[This is preliminary documentation and subject to change.]

The USER_INFO_4 structure contains information about a user account, including the account name, password data, privilege level, the path to the user's home directory, security identifier (SID), and other user-related network statistics.

Whistler: Note that the USER_INFO_4 structure supersedes the USER_INFO_3 structure. It is recommended that you use USER_INFO_4 instead of the USER_INFO_3 structure.

This structure is valid only to Windows NT/Windows 2000 servers and not LAN Manager 2.x servers.

typedef struct _USER_INFO_4 {
  LPWSTR    usri4_name;
  LPWSTR    usri4_password;
  DWORD     usri4_password_age;
  DWORD     usri4_priv;
  LPWSTR    usri4_home_dir;
  LPWSTR    usri4_comment;
  DWORD     usri4_flags;
  LPWSTR    usri4_script_path;
  DWORD     usri4_auth_flags;
  LPWSTR    usri4_full_name;
  LPWSTR    usri4_usr_comment;
  LPWSTR    usri4_parms;
  LPWSTR    usri4_workstations;
  DWORD     usri4_last_logon;
  DWORD     usri4_last_logoff;
  DWORD     usri4_acct_expires;
  DWORD     usri4_max_storage;
  DWORD     usri4_units_per_week;
  PBYTE     usri4_logon_hours;
  DWORD     usri4_bad_pw_count;
  DWORD     usri4_num_logons;
  LPWSTR    usri4_logon_server;
  DWORD     usri4_country_code;
  DWORD     usri4_code_page;
  PSID      usri4_user_sid;
  DWORD     usri4_primary_group_id;
  LPWSTR    usri4_profile;
  LPWSTR    usri4_home_dir_drive;
  DWORD     usri4_password_expired;
}USER_INFO_4, *PUSER_INFO_4, *LPUSER_INFO_4;

Members

usri4_name
Pointer to a Unicode string that specifies the name of the user account. For the NetUserSetInfo function, this member is ignored. The number of characters in the name cannot exceed the value of UNLEN.
usri4_password
Pointer to a Unicode string that specifies the password for the user identified by the usri4_name member. The length cannot exceed PWLEN bytes. The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security.

By convention, Windows NT/Windows 2000 limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT/Windows 2000 server using the account.

usri4_password_age
Specifies a DWORD value that indicates the number of seconds that have elapsed since the usri4_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri4_priv
Specifies a DWORD value that indicates the level of privilege assigned to the usri4_name member. The NetUserAdd and NetUserSetInfo functions ignore this member. This member can be one of the following values.
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri4_home_dir
Pointer to a Unicode string specifying the path of the home directory of the user specified by the usri4_name member. The string can be null.
usri4_comment
Pointer to a Unicode string that contains a comment to associate with the user account. The string can be a null string, or it can have any number of characters before the terminating null character.
usri4_flags
Specifies a DWORD value that determines several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 and Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT/Windows 2000.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. You can call the NetUserSetInfo function to clear this value and unlock a previously locked account. You cannot use this value to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT/2000 or later: The password should never expire on the account.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Windows 2000 or later: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or a Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri4_script_path
Pointer to a Unicode string specifying the path for the user's logon script file. The script file can be a .CMD file, an .EXE file, or a .BAT file. The string can also be null.
usri4_auth_flags
Specifies a DWORD value that contains a set of bit flags defining the user's operator privileges.

For the NetUserGetInfo and NetUserEnum functions, the appropriate value is returned based on the local group membership. If the user is a member of Print Operators, AF_OP_PRINT is set. If the user is a member of Server Operators, AF_OP_SERVER is set. If the user is a member of the Account Operators, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

The NetUserAdd and NetUserSetInfo functions ignore this member.

This member can be one or more of the following values.
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri4_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri4_usr_comment
Pointer to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri4_parms
Pointer to a Unicode string that is reserved for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri4_workstations
Pointer to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas. If you do not want to restrict the number of workstations, use a null string. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri4_flags member.
usri4_last_logon
Specifies a DWORD value that indicates when the last logon occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. This member is ignored by the NetUserAdd and NetUserSetInfo functions.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logon occurred at the time indicated by the largest retrieved value.

usri4_last_logoff
Specifies a DWORD value that indicates when the last logoff occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. A value of zero indicates that the last logoff time is unknown.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logoff occurred at the time indicated by the largest retrieved value.

usri4_acct_expires
Specifies a DWORD value that indicates when the account expires. This value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970, GMT. A value of TIMEQ_FOREVER indicates that the account never expires.
usri4_max_storage
Specifies a DWORD value that indicates the maximum amount of disk space the user can use. Specify USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri4_units_per_week
Specifies a DWORD value that indicates the number of equal-length time units into which the week is divided. This value is required to compute the length of the bit string in the usri4_logon_hours member.

This value must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored by the NetUserAdd and NetUserSetInfo functions.

Windows NT/2000 or later: For Windows NT/Windows 2000 services, the units must be one of the following values: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.

usri4_logon_hours
Pointer to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, in Greenwich Mean Time (GMT).

The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus 8 hours for Pacific Standard Time).

Specify a null pointer in this member when calling the NetUserAdd function to indicate no time restriction. Specify a null pointer when calling the NetUserSetInfo function to indicate that no change is to be made to the times during which the user can log on.

usri4_bad_pw_count
Specifies a DWORD value that indicates the number of times the user tried to log on to the account using an incorrect password. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is replicated from the primary domain controller (PDC); it is also maintained on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user tried to log on using an incorrect password is the largest value retrieved.

usri4_num_logons
Specifies a DWORD value that indicates the number of times the user logged on successfully to this account. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user logged on successfully is the sum of the retrieved values.

usri4_logon_server
Pointer to a Unicode string that contains the name of the server to which logon requests are sent. Server names should be preceded by two backslashes (\\). To indicate that the logon request can be handled by any logon server, specify an asterisk (\\*) for the server name. A null string indicates that requests should be sent to the domain controller. For Windows NT/Windows 2000 servers, NetUserGetInfo and NetUserEnum return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri4_country_code
Specifies a DWORD value that contains the country/region code for the user's language of choice.
usri4_code_page
Specifies a DWORD value that contains the code page for the user's language of choice.
usri4_user_sid
Pointer to a SID structure that contains the security identifier (SID) that uniquely identifies the user. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri4_primary_group_id
Specifies a DWORD value that contains the RID of the Primary Global Group for the user. When you call the NetUserAdd function, this member must be DOMAIN_GROUP_RID_USERS (defined in NTSEAPI.H). When you call NetUserSetInfo, this member must be the RID of a global group in which the user is enrolled.
usri4_profile
Pointer to a Unicode string that specifies a path to the user's profile. This value can be a null string, a local absolute path, or a UNC path.
usri4_home_dir_drive
Pointer to a Unicode string that specifies the drive letter assigned to the user's home directory for logon purposes.
usri4_password_expired
Specifies a DWORD value that contains password expiration information.

The NetUserGetInfo and NetUserEnum functions return zero if the password has not expired (and nonzero if it has).

When you call NetUserAdd or NetUserSetInfo, specify a nonzero value in this member to inform users that they must change their password at the next logon. To turn off this message, call NetUserSetInfo and specify zero in this member. Note that you cannot specify zero to negate the expiration of a password that has already expired.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserAdd, NetUserEnum, NetUserSetInfo, NetUserGetInfo, SID


USER_INFO_10

The USER_INFO_10 structure contains information about a user account, including the account name, comments associated with the account, and the user's full name.

typedef struct _USER_INFO_10 {
  LPWSTR    usri10_name;
  LPWSTR    usri10_comment;
  LPWSTR    usri10_usr_comment;
  LPWSTR    usri10_full_name;
}USER_INFO_10, *PUSER_INFO_10, *LPUSER_INFO_10;

Members

usri10_name
Pointer to a Unicode string that specifies the name of the user account. Calls to the NetUserSetInfo function ignore this member. The number of characters in the name cannot exceed the value of UNLEN.
usri10_comment
Pointer to a Unicode string that contains a comment associated with the user account. The string can be a null string, or can have any number of characters before the terminating null character.
usri10_usr_comment
Pointer to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri10_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserDel, NetUserEnum, NetUserSetInfo


USER_INFO_11

The USER_INFO_11 structure contains information about a user account, including the account name, privilege level, the path to the user's home directory, and other user-related network statistics.

typedef struct _USER_INFO_11 {
  LPWSTR    usri11_name;
  LPWSTR    usri11_comment;
  LPWSTR    usri11_usr_comment;
  LPWSTR    usri11_full_name;
  DWORD     usri11_priv;
  DWORD     usri11_auth_flags;
  DWORD     usri11_password_age;
  LPWSTR    usri11_home_dir;
  LPWSTR    usri11_parms;
  DWORD     usri11_last_logon;
  DWORD     usri11_last_logoff;
  DWORD     usri11_bad_pw_count;
  DWORD     usri11_num_logons;
  LPWSTR    usri11_logon_server;
  DWORD     usri11_country_code;
  LPWSTR    usri11_workstations;
  DWORD     usri11_max_storage;
  DWORD     usri11_units_per_week;
  PBYTE     usri11_logon_hours;
  DWORD     usri11_code_page;
}USER_INFO_11, *PUSER_INFO_11, *LPUSER_INFO_11;

Members

usri11_name
Pointer to a Unicode character that specifies the name of the user account. Calls to the NetUserSetInfo function ignore this member. The number of characters in the name cannot exceed the value of UNLEN.
usri11_comment
Pointer to a Unicode string that contains a comment associated with the user account. This string can be a null string, or it can have any number of characters before the terminating null character.
usri11_usr_comment
Pointer to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri11_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri11_priv
Specifies a DWORD value that indicates the level of privilege assigned to the usri11_name member. For calls to the NetUserAdd function, this member must be USER_PRIV_USER. For calls to NetUserSetInfo, this member must be the value returned from the NetUserGetInfo function or the NetUserEnum function. This member can be one of the following values.
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri11_auth_flags
Specifies a DWORD value that contains a set of bit flags defining the user's operator privileges.

Calls to the NetUserGetInfo function and the NetUserEnum function return a value based on the user's local group membership. If the user is a member of Print Operators, AF_OP_PRINT is set. If the user is a member of Server Operators, AF_OP_SERVER is set. If the user is a member of the Account Operators, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

The NetUserAdd and NetUserSetInfo functions ignore this member.

Windows NT/2000 or later: The following restrictions apply:

  • When you call the NetUserAdd function, this member must be zero.
  • When you call the NetUserSetInfo function, this member must be the value returned from a call to NetUserGetInfo or to NetUserEnum.

This member can be one or more of the following values.
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri11_password_age
Specifies a DWORD value that indicates the number of seconds that have elapsed since the usri11_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri11_home_dir
Pointer to a Unicode string specifying the path of the home directory for the user specified in the usri11_name member. The string can be null.
usri11_parms
Pointer to a Unicode string that is reserved for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri11_last_logon
Specifies a DWORD value that indicates when the last logon occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. The NetUserAdd and NetUserSetInfo functions ignore this member.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logon occurred at the time indicated by the largest retrieved value.

usri11_last_logoff
Specifies a DWORD value that indicates when the last logoff occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. A value of zero indicates that the last logoff time is unknown. The NetUserAdd function and the NetUserSetInfo function ignore this member.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logoff occurred at the time indicated by the largest retrieved value.

usri11_bad_pw_count
Specifies a DWORD value that indicates the number of times the user tried to log on to this account using an incorrect password. A value of – 1 indicates that the value is unknown. The NetUserAdd and NetUserSetInfo functions ignore this member.

This member is replicated from the primary domain controller (PDC); it is also maintained on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user tried to log on using an incorrect password is the largest value retrieved.

usri11_num_logons
Specifies a DWORD value that indicates the number of times the user has logged on successfully to this account. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user logged on successfully is the sum of the retrieved values.

usri11_logon_server
Pointer to a Unicode string that contains the name of the server to which logon requests are sent. Server names should be preceded by two backslashes (\\). To indicate that the logon request can be handled by any logon server, specify an asterisk (\\*) for the server name. A null string indicates that requests should be sent to the domain controller.

Windows NT/2000 or later: For Windows NT/Windows 2000 servers, NetUserGetInfo and NetUserEnum return \\*. The NetUserAdd and NetUserSetInfo functions ignore this member.

usri11_country_code
Specifies a DWORD value that contains the country/region code for the user's language of choice.
usri11_workstations
Pointer to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas. A null string indicates that there is no restriction. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri11_flags member.
usri11_max_storage
Specifies a DWORD value that indicates the maximum amount of disk space the user can use. Specify USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri11_units_per_week
Specifies a DWORD value that indicates the number of equal-length time units into which the week is divided. This value is required to compute the length of the bit string in the usri2_logon_hours member.

This member must be UNITS_PER_WEEK for LAN Manager 2.0. This element is ignored by the NetUserAdd and NetUserSetInfo functions.

Windows NT/2000 or later: For Windows NT/Windows 2000 services, the units must be one of the following values: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.

usri11_logon_hours
Pointer to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, in Greenwich Mean Time (GMT).

The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus 8 hours for Pacific Standard Time).

Specify a null pointer in this member when calling the NetUserAdd function to indicate no time restriction. Specify a null pointer when calling the NetUserSetInfo function to indicate that no change is to be made to the times during which the user can log on.

usri11_code_page
Specifies a DWORD value that indicates the code page for the user's language of choice.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserAdd, NetUserDel, NetUserEnum, NetUserGetInfo, NetUserSetInfo


USER_INFO_20

The USER_INFO_20 structure contains information about a user account, including the account name, the user's full name, a comment associated with the account, and the user's relative ID (RID).

Whistler: On Whistler and later, it is recommended that you use the USER_INFO_23 structure instead.

typedef struct _USER_INFO_20 {
  LPWSTR    usri20_name;
  LPWSTR    usri20_full_name;
  LPWSTR    usri20_comment;
  DWORD     usri20_flags;
  DWORD     usri20_user_id;
}USER_INFO_20, *PUSER_INFO_20, *LPUSER_INFO_20;

Members

usri20_name
Pointer to a Unicode string that specifies the name of the user account. Calls to the NetUserSetInfo function ignore this member. The number of characters in the name cannot exceed the value of UNLEN.
usri20_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri20_comment
Pointer to a Unicode string that contains a comment associated with the user account. This string can be a null string, or it can have any number of characters before the terminating null character.
usri20_flags
Specifies a DWORD value that determines several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT/Windows 2000.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. You can call the NetUserSetInfo function to clear this value and unlock a previously locked account. You cannot use this value to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT/2000 or later: The password should never expire on the account.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Window 2000: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri20_user_id
Specifies a DWORD value that contains the user's RID. The RID is determined by the Security Account Manager (SAM) when the user is created. It uniquely defines this user account to SAM within the domain. The NetUserAdd and NetUserSetInfo functions ignore this member.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserAdd, NetUserEnum, NetUserSetInfo


USER_INFO_21

The USER_INFO_21 structure contains a one-way encrypted LAN Manager 2.x-compatible password.

typedef struct _USER_INFO_21 {
  BYTE    usri21_password[ENCRYPTED_PWLEN];
}USER_INFO_21, *PUSER_INFO_21, *LPUSER_INFO_21;

Members

usri21_password
Specifies a one-way encrypted LAN Manager 2.x-compatible password.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_22

The USER_INFO_22 structure contains information about a user account, including the account name, privilege level, the path to the user's home directory, a one-way encrypted LAN Manager 2.x-compatible password, and other user-related network statistics.

typedef struct _USER_INFO_22 {
  LPWSTR    usri22_name;
  BYTE      usri22_password[ENCRYPTED_PWLEN];
  DWORD     usri22_password_age;
  DWORD     usri22_priv;
  LPWSTR    usri22_home_dir;
  LPWSTR    usri22_comment;
  DWORD     usri22_flags;
  LPWSTR    usri22_script_path;
  DWORD     usri22_auth_flags;
  LPWSTR    usri22_full_name;
  LPWSTR    usri22_usr_comment;
  LPWSTR    usri22_parms;
  LPWSTR    usri22_workstations;
  DWORD     usri22_last_logon;
  DWORD     usri22_last_logoff;
  DWORD     usri22_acct_expires;
  DWORD     usri22_max_storage;
  DWORD     usri22_units_per_week;
  PBYTE     usri22_logon_hours;
  DWORD     usri22_bad_pw_count;
  DWORD     usri22_num_logons;
  LPWSTR    usri22_logon_server;
  DWORD     usri22_country_code;
  DWORD     usri22_code_page;
}USER_INFO_22, *PUSER_INFO_22, *LPUSER_INFO_22;

Members

usri22_name
Pointer to a Unicode string that specifies the name of the user account. Calls to the NetUserSetInfo function ignore this member.
usri22_password
Specifies a one-way encrypted LAN Manager 2.x-compatible password.
usri22_password_age
Specifies a DWORD value that indicates the number of seconds that have elapsed since the usri22_password member was last changed. The NetUserAdd and NetUserSetInfo functions ignore this member.
usri22_priv
Specifies a DWORD value that indicates the level of privilege assigned to the usri22_name member. Calls to the NetUserAdd function must specify USER_PRIV_USER. When you call the NetUserSetInfo function this member must be the value returned from the NetUserGetInfo or the NetUserEnum function. This member can be one of the following values.
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

usri22_home_dir
Pointer to a Unicode string specifying the path of the home directory for the user specified by the usri22_name member. The string can be null.
usri22_comment
Pointer to a Unicode string that contains a comment associated with the user account. This string can be a null string, or it can have any number of characters before the terminating null character.
usri22_flags
Specifies a DWORD value that determines several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT/Windows 2000.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. You can call the NetUserSetInfo function to clear this value and unlock a previously locked account. You cannot use this value to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT/2000 or later: The password should never expire on the account.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Windows 2000 or later: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri22_script_path
Pointer to a Unicode string specifying the path for the user's logon script file. The script file can be a .CMD file, an .EXE file, or a .BAT file. The string can also be null.
usri22_auth_flags
Specifies a DWORD value that contains a set of bit flags defining the user's operator privileges.

Calls to the NetUserGetInfo function and the NetUserEnum function return a value based on the user's local group membership. If the user is a member of Print Operators, AF_OP_PRINT is set. If the user is a member of Server Operators, AF_OP_SERVER is set. If the user is a member of the Account Operators, AF_OP_ACCOUNTS is set. AF_OP_COMM is never set.

Windows NT/2000 or later: The following restrictions apply:

  • When you call the NetUserAdd function, this member must be zero.
  • When you call the NetUserSetInfo function, this member must be the value returned from a call to NetUserGetInfo or to NetUserEnum.

This member can be one or more of the following values.
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

usri22_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri22_usr_comment
Pointer to a Unicode string that contains a user comment. This string can be a null string, or it can have any number of characters before the terminating null character.
usri22_parms
Pointer to a Unicode string that is reserved for use by applications. This string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.
usri22_workstations
Pointer to a Unicode string that contains the names of workstations from which the user can log on. As many as eight workstations can be specified; the names must be separated by commas. A null string indicates that there is no restriction. To disable logons from all workstations to this account, set the UF_ACCOUNTDISABLE value in the usri22_flags member.
usri22_last_logon
Specifies a DWORD value that indicates when the last logon occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. Calls to the NetUserAdd and the NetUserSetInfo functions ignore this member.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logon occurred at the time indicated by the largest retrieved value.

usri22_last_logoff
Specifies a DWORD value that indicates when the last logoff occurred. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. A value of zero means that the last logoff time is unknown. This element is ignored by calls to NetUserAdd and NetUserSetInfo.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The last logoff occurred at the time indicated by the largest retrieved value.

usri22_acct_expires
Specifies when the account expires. This value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. A value of TIMEQ_FOREVER indicates that the account never expires.
usri22_max_storage
Specifies a DWORD value that indicates the maximum amount of disk space the user can use. Specify USER_MAXSTORAGE_UNLIMITED to use all available disk space.
usri22_units_per_week
Specifies the number of equal-length time units into which the week is divided. This value is required to compute the length of the bit string in the usri22_logon_hours member.

This value must be UNITS_PER_WEEK for LAN Manager 2.0. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

Windows NT/2000 or later: For Windows NT/Windows 2000 services, the units must be one of the following: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.

usri22_logon_hours
Pointer to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. Each bit represents a unique hour in the week, in Greenwich Mean Time (GMT).

The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus 8 hours for Pacific Standard Time).

Specify a null pointer in this member when calling the NetUserAdd function to indicate no time restriction. Specify a null pointer when calling the NetUserSetInfo function to indicate that no change is to be made to the times during which the user can log on.

usri22_bad_pw_count
Specifies a DWORD value that indicates the number of times the user tried to log on to this account using an incorrect password. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is replicated from the primary domain controller (PDC); it is also maintained on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user tried to log on using an incorrect password is the largest value retrieved.

usri22_num_logons
Specifies a DWORD value that indicates the number of times the user logged on successfully to this account. A value of – 1 indicates that the value is unknown. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

This member is maintained separately on each backup domain controller (BDC) in the domain. To obtain an accurate value, you must query each BDC in the domain. The number of times the user logged on successfully is the sum of the retrieved values.

usri22_logon_server
Pointer to a Unicode string that contains the name of the server to which logon requests are sent. Server names should be preceded by two backslashes (\\). To indicate that the logon request can be handled by any logon server, specify an asterisk (\\*) for the server name. A null string indicates that requests should be sent to the domain controller.

Windows NT/2000 or later: For Windows NT/Windows 2000 servers, the NetUserGetInfo and NetUserEnum functions return \\*. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

usri22_country_code
Specifies a DWORD value that contains the country/region code for the user's language of choice.

Windows NT/2000 or later: Windows NT/Windows 2000 does not use the country/region code.

usri22_code_page
Specifies a DWORD value that contains the code page for the user's language of choice. Windows NT/Windows 2000 does not use the code page.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserAdd, NetUserEnum, NetUserGetInfo, NetUserSetInfo


USER_INFO_23

[This is preliminary documentation and subject to change.]

The USER_INFO_23 structure contains information about a user account, including the account name, the user's full name, a comment associated with the account, and the user's security identifier (SID).

Whistler: Note that the USER_INFO_23 structure supersedes the USER_INFO_20 structure. It is recommended that you use USER_INFO_23 instead of the USER_INFO_20 structure.

typedef struct _USER_INFO_23 {
  LPWSTR    usri23_name;
  LPWSTR    usri23_full_name;
  LPWSTR    usri23_comment;
  DWORD     usri23_flags;
  PSID      usri23_user_sid;
}USER_INFO_23, *PUSER_INFO_23, *LPUSER_INFO_23;

Members

usri23_name
Pointer to a Unicode string that specifies the name of the user account. Calls to the NetUserSetInfo function ignore this member. The number of characters in the name cannot exceed the value of UNLEN.
usri23_full_name
Pointer to a Unicode string that contains the full name of the user. This string can be a null string, or it can have any number of characters before the terminating null character.
usri23_comment
Pointer to a Unicode string that contains a comment associated with the user account. This string can be a null string, or it can have any number of characters before the terminating null character.
usri23_flags
Specifies a DWORD value that determines several features. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 or Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT/Windows 2000.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. You can call the NetUserSetInfo function to clear this value and unlock a previously locked account. You cannot use this value to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT/2000 or later: The password should never expire on the account.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Window 2000: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

usri23_user_sid
Pointer to a SID structure that contains the security identifier (SID) that uniquely identifies the user. The NetUserAdd and NetUserSetInfo functions ignore this member.

Requirements

Windows NT/2000 or later: Requires Whistler.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserAdd, NetUserEnum, NetUserSetInfo, SID


USER_INFO_1003

The USER_INFO_1003 structure contains a user password. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1003 {
  LPWSTR    usri1003_password;
} USER_INFO_1003, *PUSER_INFO_1003, *LPUSER_INFO_1003;

Members

usri1003_password
Specifies a Unicode string that contains the password for the user account specified in the username parameter to the NetUserSetInfo function. The length cannot exceed PWLEN bytes.

The NetUserEnum and NetUserGetInfo functions return a NULL pointer to maintain password security.

Remarks

By convention, Windows NT/Windows 2000 limits the length of passwords to LM20_PWLEN characters. This convention allows LAN Manager, Windows 3.x, Windows for Workgroups 3.x, Windows 95, and Windows 98 clients to access a Windows NT/Windows 2000 server using the account.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserEnum, NetUserGetInfo, NetUserSetInfo


USER_INFO_1005

The USER_INFO_1005 structure contains a privilege level to assign to a user network account. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1005 {
  DWORD    usri1005_priv;
} USER_INFO_1005, *PUSER_INFO_1005, *LPUSER_INFO_1005;

Members

usri1005_priv
Specifies a DWORD value that indicates the level of privilege to assign for the user account specified in the username parameter to the NetUserSetInfo function. This member can be one of the following values.
Value | Meaning
USER_PRIV_GUEST | Guest
USER_PRIV_USER | User
USER_PRIV_ADMIN | Administrator

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1006

The USER_INFO_1006 structure contains the user's home directory path. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1006 {
  LPWSTR    usri1006_home_dir;
} USER_INFO_1006, *PUSER_INFO_1006, *LPUSER_INFO_1006;

Members

usri1006_home_dir
Pointer to a Unicode string specifying the path of the home directory for the user account specified in the username parameter to the NetUserSetInfo function. The string can be null.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1007

The USER_INFO_1007 structure contains a comment associated with a user network account. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1007 {
  LPWSTR    usri1007_comment;
} USER_INFO_1007, *PUSER_INFO_1007, *LPUSER_INFO_1007;

Members

usri1007_comment
Pointer to a Unicode string that contains a comment to associate with the user account specified in the username parameter to the NetUserSetInfo function. This string can be a null string, or it can have any number of characters before the terminating null character.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1008

The USER_INFO_1008 structure contains a set of bit flags defining several user network account parameters. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1008 {
  DWORD    usri1008_flags;
} USER_INFO_1008, *PUSER_INFO_1008, *LPUSER_INFO_1008;

Members

usri1008_flags
Specifies a DWORD value that determines several features to associate with the user account specified in the username parameter to the NetUserSetInfo function. This member can be one or more of the following values.
Value | Meaning
UF_SCRIPT | The logon script executed. This value must be set for LAN Manager 2.0 and Windows NT/Windows 2000.
UF_ACCOUNTDISABLE | The user's account is disabled.
UF_HOMEDIR_REQUIRED | The home directory is required. This value is ignored in Windows NT/Windows 2000.
UF_PASSWD_NOTREQD | No password is required.
UF_PASSWD_CANT_CHANGE | The user cannot change the password.
UF_LOCKOUT | The account is currently locked out. You can call the NetUserSetInfo function to clear this value and unlock a previously locked account. You cannot use this value to lock a previously unlocked account.
UF_DONT_EXPIRE_PASSWD | Windows NT/2000 or later: The password should never expire on the account.
UF_ENCRYPTED_TEXT_PASSWORD_ALLOWED | Windows 2000 or later: The user's password is stored under reversible encryption in the Active Directory.
UF_NOT_DELEGATED | Windows 2000 or later: Marks the account as "sensitive"; other users cannot act as delegates of this user account.
UF_SMARTCARD_REQUIRED | Windows 2000 or later: Requires the user to log on to the user account with a smart card.
UF_USE_DES_KEY_ONLY | Windows 2000 or later: Restrict this principal to use only Data Encryption Standard (DES) encryption types for keys.
UF_DONT_REQUIRE_PREAUTH | Windows 2000 or later: This account does not require Kerberos preauthentication for logon.
UF_TRUSTED_FOR_DELEGATION | Windows 2000 or later: The account is enabled for delegation. This is a security-sensitive setting; accounts with this option enabled should be tightly controlled. This setting allows a service running under the account to assume a client's identity and authenticate as that user to other remote servers on the network.
UF_PASSWORD_EXPIRED | Whistler: The user's password has expired.

The following values describe the account type. Only one value can be set. You cannot change the account type using the NetUserSetInfo function.
Value | Meaning
UF_NORMAL_ACCOUNT | This is a default account type that represents a typical user.
UF_TEMP_DUPLICATE_ACCOUNT | This is an account for users whose primary account is in another domain. This account provides user access to this domain, but not to any domain that trusts this domain. The User Manager refers to this account type as a local user account.
UF_WORKSTATION_TRUST_ACCOUNT | This is a computer account for a Windows NT/Windows 2000 workstation or a Windows NT/Windows 2000 server that is a member of this domain.
UF_SERVER_TRUST_ACCOUNT | This is a computer account for a backup domain controller that is a member of this domain.
UF_INTERDOMAIN_TRUST_ACCOUNT | This is a permit to trust account for a domain that trusts other domains.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1009

The USER_INFO_1009 structure contains the path for a user's logon script file. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1009 {
  LPWSTR    usri1009_script_path;
} USER_INFO_1009, *PUSER_INFO_1009, *LPUSER_INFO_1009;

Members

usri1009_script_path
Pointer to a Unicode string specifying the path for the user's logon script file. The user is specified in the username parameter to the NetUserSetInfo function. The script file can be a .CMD file, an .EXE file, or a .BAT file. The string can also be null.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1010

The USER_INFO_1010 structure contains a set of bit flags defining the operator privileges assigned to a user network account. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1010 {
  DWORD    usri1010_auth_flags;
} USER_INFO_1010, *PUSER_INFO_1010, *LPUSER_INFO_1010;

Members

usri1010_auth_flags
Specifies a DWORD value that contains a set of bit flags that specify the user's operator privileges. The user is specified in the username parameter to the NetUserSetInfo function.

This member can be one or more of the following values.
Value | Meaning
AF_OP_PRINT | The print operator privilege is enabled.
AF_OP_COMM | The communications operator privilege is enabled.
AF_OP_SERVER | The server operator privilege is enabled.
AF_OP_ACCOUNTS | The accounts operator privilege is enabled.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1011

The USER_INFO_1011 structure contains the full name of a network user. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1011 {
  LPWSTR    usri1011_full_name;
} USER_INFO_1011, *PUSER_INFO_1011, *LPUSER_INFO_1011;

Members

usri1011_full_name
Pointer to a Unicode string that contains the full name of the user. The user is specified in the username parameter to the NetUserSetInfo function. This string can be a null string, or it can have any number of characters before the terminating null character.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1012

The USER_INFO_1012 structure contains a user comment. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1012 {
  LPWSTR    usri1012_usr_comment;
} USER_INFO_1012, *PUSER_INFO_1012, *LPUSER_INFO_1012;

Members

usri1012_usr_comment
Pointer to a Unicode string that contains a user comment. The user is specified in the username parameter to the NetUserSetInfo function. This string can be a null string, or it can have any number of characters before the terminating null character.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1013

The USER_INFO_1013 structure contains reserved information for network accounts. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1013 {
  LPWSTR    usri1013_parms;
} USER_INFO_1013, *PUSER_INFO_1013, *LPUSER_INFO_1013;

Members

usri1013_parms
Pointer to a Unicode string that is reserved for use by applications. The string can be a null string, or it can have any number of characters before the terminating null character. Microsoft products use this member to store user configuration information. Do not modify this information.

The Windows NT/Windows 2000 components that use this member are services for Macintosh, file and print services for NetWare, and the Remote Access Server (RAS).

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1014

The USER_INFO_1014 structure contains the names of workstations from which the user can log on. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1014 {
  LPWSTR    usri1014_workstations;
} USER_INFO_1014, *PUSER_INFO_1014, *LPUSER_INFO_1014;

Members

usri1014_workstations
Pointer to a Unicode string that contains the names of workstations from which the user can log on. The user is specified in the username parameter to the NetUserSetInfo function.

As many as eight workstations can be specified; the names must be separated by commas. A null string indicates that there is no restriction.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1017

The USER_INFO_1017 structure contains expiration information for network user accounts. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1017 {
  DWORD    usri1017_acct_expires;
} USER_INFO_1017, *PUSER_INFO_1017, *LPUSER_INFO_1017;

Members

usri1017_acct_expires
Specifies a DWORD value that indicates when the user account expires. The user account is specified in the username parameter to the NetUserSetInfo function.

The value is stored as the number of seconds that have elapsed since 00:00:00, January 1, 1970, GMT. Specify TIMEQ_FOREVER to indicate that the account never expires.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1018

The USER_INFO_1018 structure contains the maximum amount of disk space available to a network user account. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1018 {
  DWORD    usri1018_max_storage;
} USER_INFO_1018, *PUSER_INFO_1018, *LPUSER_INFO_1018;

Members

usri1018_max_storage
Specifies a DWORD value that indicates the maximum amount of disk space the user can use. The user is specified in the username parameter to the NetUserSetInfo function.

Windows NT/2000 or later: For Windows NT/Windows 2000, you must specify USER_MAXSTORAGE_UNLIMITED to indicate that there is no restriction on disk space.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1020

The USER_INFO_1020 structure contains the times during which a user can log on to the network. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1020 {
    DWORD     usri1020_units_per_week;
    LPBYTE    usri1020_logon_hours;
} USER_INFO_1020, *PUSER_INFO_1020, *LPUSER_INFO_1020;

Members

usri1020_units_per_week
Specifies a DWORD value that indicates the number of equal-length time units into which the week is divided. This value is required to compute the length of the bit string in the usri1020_logon_hours member.

This value must be UNITS_PER_WEEK for LAN Manager 2.0. Calls to the NetUserAdd and NetUserSetInfo functions ignore this member.

Windows NT/2000 or later: For Windows NT/Windows 2000 services, the units must be one of the following values: SAM_DAYS_PER_WEEK, SAM_HOURS_PER_WEEK, or SAM_MINUTES_PER_WEEK.

usri1020_logon_hours
Pointer to a 21-byte (168 bits) bit string that specifies the times during which the user can log on. The user is specified in the username parameter to the NetUserSetInfo function.

Each bit in the string represents a unique hour in the week, in Greenwich Mean Time (GMT). The first bit (bit 0, word 0) is Sunday, 0:00 to 0:59; the second bit (bit 1, word 0) is Sunday, 1:00 to 1:59; and so on. Note that bit 0 in word 0 represents Sunday from 0:00 to 0:59 only if you are in the GMT time zone. In all other cases you must adjust the bits according to your time zone offset (for example, GMT minus 8 hours for Pacific Standard Time).

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1023

The USER_INFO_1023 structure contains the name of the server to which network logon requests should be sent. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1023 {
  LPWSTR    usri1023_logon_server;
} USER_INFO_1023, *PUSER_INFO_1023, *LPUSER_INFO_1023;

Members

usri1023_logon_server
Pointer to a Unicode string that contains the name of the server to which logon requests for the user account should be sent. The user account is specified in the username parameter to the NetUserSetInfo function.

Server names should be preceded by two backslashes (\\). To indicate that the logon request can be handled by any logon server, specify an asterisk (\\*) for the server name. A null string indicates that requests should be sent to the domain controller.

Windows NT/2000 or later: For Windows NT/Windows 2000 servers, the NetUserSetInfo function does not support this level.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1024

The USER_INFO_1024 structure contains the country/region code for a network user's language of choice. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1024 {
  DWORD    usri1024_country_code;
} USER_INFO_1024, *PUSER_INFO_1024, *LPUSER_INFO_1024;

Members

usri1024_country_code
Specifies a DWORD value that indicates the country/region code for the user's language of choice. The user is specified in the username parameter to the NetUserSetInfo function.

Windows NT/2000 or later: Windows NT/Windows 2000 does not use the country/region code.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1025

The USER_INFO_1025 structure contains the code page for a network user's language of choice. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1025 {
  DWORD    usri1025_code_page;
} USER_INFO_1025, *PUSER_INFO_1025, *LPUSER_INFO_1025;

Members

usri1025_code_page
Specifies a DWORD value that indicates the code page for the user's language of choice. The user is specified in the username parameter to the NetUserSetInfo function.

Windows NT/2000 or later: Windows NT/Windows 2000 does not use the code page.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1051

The USER_INFO_1051 structure contains the relative ID (RID) associated with the user account. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1051 {
  DWORD    usri1051_primary_group_id;
} USER_INFO_1051, *PUSER_INFO_1051, *LPUSER_INFO_1051;

Members

usri1051_primary_group_id
Specifies a DWORD value that contains the RID of the Primary Global Group for the user specified in the username parameter to the NetUserSetInfo function. This member must be the RID of a global group that represents the enrolled user.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1052

The USER_INFO_1052 structure contains the path to a network user's profile. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1052 {
  LPWSTR    usri1052_profile;
} USER_INFO_1052, *PUSER_INFO_1052, *LPUSER_INFO_1052;

Members

usri1052_profile
Specifies a Unicode string that contains the path to the user's profile. The user is specified in the username parameter to the NetUserSetInfo function. This value can be a null string, a local absolute path, or a UNC path.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_INFO_1053

The USER_INFO_1053 structure contains user information for network accounts. This information level is valid only when you call the NetUserSetInfo function.

typedef struct _USER_INFO_1053 {
  LPWSTR    usri1053_home_dir_drive;
} USER_INFO_1053, *PUSER_INFO_1053, *LPUSER_INFO_1053;

Members

usri1053_home_dir_drive
Specifies the drive letter to assign to the user's home directory for logon purposes. The user is specified in the username parameter to the NetUserSetInfo function.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Functions, NetUserSetInfo


USER_MODALS_INFO_0

The USER_MODALS_INFO_0 structure contains global password information for users and global groups in a security database.

typedef struct _USER_MODALS_INFO_0 {
  DWORD    usrmod0_min_passwd_len;
  DWORD    usrmod0_max_passwd_age;
  DWORD    usrmod0_min_passwd_age;
  DWORD    usrmod0_force_logoff;
  DWORD    usrmod0_password_hist_len;
}USER_MODALS_INFO_0, *PUSER_MODALS_INFO_0, *LPUSER_MODALS_INFO_0;

Members

usrmod0_min_passwd_len
Specifies the minimum allowable password length. Valid values for this element are zero through PWLEN.
usrmod0_max_passwd_age
Specifies, in seconds, the maximum allowable password age. A value of TIMEQ_FOREVER indicates that the password never expires. The minimum valid value for this element is ONE_DAY. The value specified must be greater than or equal to the value for the usrmod0_min_passwd_age member.
usrmod0_min_passwd_age
Specifies the minimum number of seconds that can elapse between the time a password changes and when it can be changed again. A value of zero indicates that no delay is required between password updates. The value specified must be less than or equal to the value for the usrmod0_max_passwd_age member.
usrmod0_force_logoff
Specifies, in seconds, the amount of time between the end of the valid logon time and the time when the user is forced to log off the network. A value of TIMEQ_FOREVER indicates that the user is never forced to log off. A value of zero indicates that the user will be forced to log off immediately when the valid logon time expires.
usrmod0_password_hist_len
Specifies the length of password history maintained. A new password cannot match any of the previous usrmod0_password_hist_len passwords. Valid values for this element are zero through DEF_MAX_PWHIST.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsGet, NetUserModalsSet


USER_MODALS_INFO_1

The USER_MODALS_INFO_1 structure contains logon server and domain controller information.

typedef struct _USER_MODALS_INFO_1 {
  DWORD    usrmod1_role;
  LPWSTR   usrmod1_primary;
}USER_MODALS_INFO_1, *PUSER_MODALS_INFO_1, *LPUSER_MODALS_INFO_1;

Members

usrmod1_role
Specifies the role of the logon server. The following values are defined.
Value | Meaning
UAS_ROLE_STANDALONE | The logon server is a stand-alone server.
UAS_ROLE_MEMBER | The logon server is a member.
UAS_ROLE_BACKUP | The logon server is a backup.
UAS_ROLE_PRIMARY | The logon server is a domain controller.

If the Netlogon service is not being used, the element should be set to UAS_ROLE_STANDALONE.

usrmod1_primary
Pointer to a Unicode string that specifies the name of the domain controller that stores the primary copy of the database for the user account manager.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsGet, NetUserModalsSet


USER_MODALS_INFO_2

The USER_MODALS_INFO_2 structure contains the Security Account Manager (SAM) domain name and identifier.

typedef struct _USER_MODALS_INFO_2 {
  LPWSTR  usrmod2_domain_name;
  PSID    usrmod2_domain_id;
}USER_MODALS_INFO_2, *PUSER_MODALS_INFO_2, *LPUSER_MODALS_INFO_2;

Members

usrmod2_domain_name
Specifies the name of the Security Account Manager (SAM) domain. For a domain controller, this is the name of the domain that the controller is a member of. For Windows NT/Windows 2000 workstations, this is the name of the computer.
usrmod2_domain_id
Pointer to a Unicode string that specifies the domain security identifier of the domain named by the usrmod2_domain_name member.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsGet, NetUserModalsSet


USER_MODALS_INFO_3

The USER_MODALS_INFO_3 structure contains lockout information for users and global groups in a security database.

typedef struct _USER_MODALS_INFO_3 {
  DWORD   usrmod3_lockout_duration;
  DWORD   usrmod3_lockout_observation_window;
  DWORD   usrmod3_lockout_threshold;
}USER_MODALS_INFO_3, *PUSER_MODALS_INFO_3, *LPUSER_MODALS_INFO_3;

Members

usrmod3_lockout_duration
Specifies, in seconds, how long a locked account remains locked before it is automatically unlocked.
usrmod3_lockout_observation_window
Specifies the maximum time, in seconds, that can elapse between any two failed logon attempts before lockout occurs.
usrmod3_lockout_threshold
Specifies the number of invalid password authentications that can occur before an account is marked "locked out."

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsGet, NetUserModalsSet


USER_MODALS_INFO_1001

The USER_MODALS_INFO_1001 structure contains the minimum length for passwords in a security database.

typedef struct _USER_MODALS_INFO_1001 {
  DWORD    usrmod1001_min_passwd_len;
}USER_MODALS_INFO_1001, *PUSER_MODALS_INFO_1001, *LPUSER_MODALS_INFO_1001;

Members

usrmod1001_min_passwd_len
Specifies the minimum allowable password length. Valid values for this element are zero through PWLEN.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsSet


USER_MODALS_INFO_1002

The USER_MODALS_INFO_1002 structure contains the maximum duration for passwords in a security database.

typedef struct _USER_MODALS_INFO_1002 {
  DWORD    usrmod1002_max_passwd_age;
}USER_MODALS_INFO_1002, *PUSER_MODALS_INFO_1002, *LPUSER_MODALS_INFO_1002;

Members

usrmod1002_max_passwd_age
Specifies, in seconds, the maximum allowable password age. A value of TIMEQ_FOREVER indicates that the password never expires. The minimum valid value for this element is ONE_DAY. The value specified must be greater than or equal to the value for the usrmodX_min_passwd_age member.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsSet


USER_MODALS_INFO_1003

The USER_MODALS_INFO_1003 structure contains the minimum duration for passwords in a security database.

typedef struct _USER_MODALS_INFO_1003 {
  DWORD    usrmod1003_min_passwd_age;
}USER_MODALS_INFO_1003, *PUSER_MODALS_INFO_1003, *LPUSER_MODALS_INFO_1003;

Members

usrmod1003_min_passwd_age
Specifies the minimum number of seconds that can elapse between the time a password changes and when it can be changed again. A value of zero indicates that no delay is required between password updates. The value specified must be less than or equal to the value for the usrmodX_max_passwd_age member.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsSet


USER_MODALS_INFO_1004

The USER_MODALS_INFO_1004 structure contains forced logoff information for users and global groups in a security database.

typedef struct _USER_MODALS_INFO_1004 {
  DWORD    usrmod1004_force_logoff;
}USER_MODALS_INFO_1004, *PUSER_MODALS_INFO_1004, *LPUSER_MODALS_INFO_1004;

Members

usrmod1004_force_logoff
Specifies, in seconds, the amount of time between the end of the valid logon time and the time when the user is forced to log off the network. A value of TIMEQ_FOREVER indicates that the user is never forced to log off. A value of zero indicates that the user will be forced to log off immediately when the valid logon time expires.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsSet


USER_MODALS_INFO_1005

The USER_MODALS_INFO_1005 structure contains password history information for users and global groups in a security database.

typedef struct _USER_MODALS_INFO_1005 {
  DWORD    usrmod1005_password_hist_len;
}USER_MODALS_INFO_1005, *PUSER_MODALS_INFO_1005, *LPUSER_MODALS_INFO_1005;

Members

usrmod1005_password_hist_len
Specifies the length of password history that the system maintains. A new password cannot match any of the previous usrmodX_password_hist_len passwords. Valid values for this element are zero through DEF_MAX_PWHIST.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsSet


USER_MODALS_INFO_1006

The USER_MODALS_INFO_1006 structure contains logon server information.

typedef struct _USER_MODALS_INFO_1006 {
  DWORD   usrmod1006_role;
} USER_MODALS_INFO_1006, *PUSER_MODALS_INFO_1006, *LPUSER_MODALS_INFO_1006;

Members

usrmod1006_role
Specifies the role of the logon server. This member can be one of the following values.
Value | Meaning
UAS_ROLE_STANDALONE | Logon server is a stand-alone. Use this value if no logon services are available
UAS_ROLE_MEMBER | Logon server is a member.
UAS_ROLE_BACKUP | Logon server is a backup.
UAS_ROLE_PRIMARY | Logon server is a domain controller.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsSet


USER_MODALS_INFO_1007

The USER_MODALS_INFO_1007 structure contains domain controller information.

typedef struct _USER_MODALS_INFO_1007 {
  LPWSTR  usrmod1007_primary;
} USER_MODALS_INFO_1007, *PUSER_MODALS_INFO_1007, *LPUSER_MODALS_INFO_1007;

Members

usrmod1007_primary
Pointer to a Unicode string that specifies the name of the domain controller that stores the primary copy of the database for the user account manager.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmaccess.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, User Modal Functions, NetUserModalsSet


USER_OTHER_INFO

The USER_OTHER_INFO structure contains user error code information. The NetAlertRaise and NetAlertRaiseEx functions use the USER_OTHER_INFO structure to specify information about an event or condition of interest to a user.

typedef struct _USER_OTHER_INFO {
  DWORD  alrtus_errcode;
  DWORD  alrtus_numstrings;
}USER_OTHER_INFO, *PUSER_OTHER_INFO, *LPUSER_OTHER_INFO;

Members

alrtus_errcode
Specifies the error code for the new message in the message log.
alrtus_numstrings
Specifies the number (0-9) of consecutive Unicode strings in the message log.

Remarks

Additional variable-length data follows the USER_OTHER_INFO structure in the alert message buffer. The information is in the form of contiguous null-terminated character strings, as follows.

String | Meaning
username | The user who created the session.
computername | The computer that created the session.

The calling application must allocate and free the memory for all structures and variable-length data in an alert message buffer.

See NetAlertRaiseEx for a code sample that demonstrates how to raise a user alert.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Alert Functions, ADMIN_OTHER_INFO, ERRLOG_OTHER_INFO, PRINT_OTHER_INFO, STD_ALERT, NetAlertRaise, NetAlertRaiseEx


WKSTA_INFO_100

The WKSTA_INFO_100 structure contains information about a workstation environment, including platform-specific information, the names of the domain and the local computer, and information concerning the operating system.

typedef struct _WKSTA_INFO_100 {
  DWORD     wki100_platform_id;
  LPWSTR    wki100_computername;
  LPWSTR    wki100_langroup;
  DWORD     wki100_ver_major;
  DWORD     wki100_ver_minor;
}WKSTA_INFO_100, *PWKSTA_INFO_100, *LPWKSTA_INFO_100;

Members

wki100_platform_id
Specifies the information level to use to retrieve platform-specific information. This member can be one of the following values, defined in the lmcons.h file: PLATFORM_ID_DOS, PLATFORM_ID_OS2, PLATFORM_ID_NT, PLATFORM_ID_OSF, or PLATFORM_ID_VMS.
wki100_computername
Pointer to a Unicode string specifying the name of the local computer.
wki100_langroup
Pointer to a Unicode string specifying the name of the domain to which the computer belongs.
wki100_ver_major
Specifies the major version number of the operating system running on the computer.
wki100_ver_minor
Specifies the minor version number of the operating system running on the computer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Workstation and Workstation User Functions, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_INFO_101

The WKSTA_INFO_101 structure contains information about a workstation environment, including platform-specific information, the name of the domain and the local computer, and information concerning the operating system.

typedef struct _WKSTA_INFO_101 {
  DWORD     wki101_platform_id;
  LPWSTR    wki101_computername;
  LPWSTR    wki101_langroup;
  DWORD     wki101_ver_major;
  DWORD     wki101_ver_minor;
  LPWSTR    wki101_lanroot;
}WKSTA_INFO_101, *PWKSTA_INFO_101, *LPWKSTA_INFO_101;

Members

wki101_platform_id
Specifies the information level to use to retrieve platform-specific information. This member can be one of the following values, defined in the lmcons.h file: PLATFORM_ID_DOS, PLATFORM_ID_OS2, PLATFORM_ID_NT, PLATFORM_ID_OSF, or PLATFORM_ID_VMS.
wki101_computername
Pointer to a Unicode string specifying the name of the local computer.
wki101_langroup
Pointer to a Unicode string specifying the name of the domain to which the computer belongs.
wki101_ver_major
Specifies the major version number of the operating system running on the computer.
wki101_ver_minor
Specifies the minor version number of the operating system running on the computer.
wki101_lanroot
Pointer to a Unicode string that contains the path to the LANMAN directory.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Workstation and Workstation User Functions, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_INFO_102

The WKSTA_INFO_102 structure contains information about a workstation environment, including platform-specific information, the name of the domain and the local computer, and information concerning the operating system.

typedef struct _WKSTA_INFO_102 {
  DWORD     wki102_platform_id;
  LPWSTR    wki102_computername;
  LPWSTR    wki102_langroup;
  DWORD     wki102_ver_major;
  DWORD     wki102_ver_minor;
  LPWSTR    wki102_lanroot;
  DWORD     wki102_logged_on_users;
}WKSTA_INFO_102, *PWKSTA_INFO_102, *LPWKSTA_INFO_102;

Members

wki102_platform_id
Specifies the information level to use to retrieve platform-specific information. This member can be one of the following values, defined in the lmcons.h file: PLATFORM_ID_DOS, PLATFORM_ID_OS2, PLATFORM_ID_NT, PLATFORM_ID_OSF, or PLATFORM_ID_VMS.
wki102_computername
Pointer to a Unicode string specifying the name of the local computer.
wki102_langroup
Pointer to a Unicode string specifying the name of the domain to which the computer belongs.
wki102_ver_major
Specifies the major version number of the operating system running on the computer.
wki102_ver_minor
Specifies the minor version number of the operating system running on the computer.
wki102_lanroot
Pointer to a Unicode string that contains the path to the LANMAN directory.
wki102_logged_on_users
Specifies the number of users who are logged on to the local computer.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Workstation and Workstation User Functions, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_INFO_502

The WKSTA_INFO_502 structure is obsolete. The structure contains information about a workstation environment.

typedef struct _WKSTA_INFO_502{
  DWORD     wki502_char_wait;
  DWORD     wki502_collection_time;
  DWORD     wki502_maximum_collection_count;
  DWORD     wki502_keep_conn;
  DWORD     wki502_max_cmds;
  DWORD     wki502_sess_timeout;
  DWORD     wki502_siz_char_buf;
  DWORD     wki502_max_threads;

  DWORD   wki502_lock_quota;
  DWORD   wki502_lock_increment;
  DWORD   wki502_lock_maximum;
  DWORD   wki502_pipe_increment;
  DWORD   wki502_pipe_maximum;
  DWORD   wki502_cache_file_timeout;
  DWORD   wki502_dormant_file_limit;
  DWORD   wki502_read_ahead_throughput;

  DWORD   wki502_num_mailslot_buffers;
  DWORD   wki502_num_srv_announce_buffers;
  DWORD   wki502_max_illegal_datagram_events;
  DWORD   wki502_illegal_datagram_event_reset_frequency;
  BOOL    wki502_log_election_packets;

  BOOL    wki502_use_opportunistic_locking;
  BOOL    wki502_use_unlock_behind;
  BOOL    wki502_use_close_behind;
  BOOL    wki502_buf_named_pipes;
  BOOL    wki502_use_lock_read_unlock;
  BOOL    wki502_utilize_nt_caching;
  BOOL    wki502_use_raw_read;
  BOOL    wki502_use_raw_write;
  BOOL    wki502_use_write_raw_data;
  BOOL    wki502_use_encryption;
  BOOL    wki502_buf_files_deny_write;
  BOOL    wki502_buf_read_only_files;
  BOOL    wki502_force_core_create_mode;
  BOOL    wki502_use_512_byte_max_transfer;
}WKSTA_INFO_502, *PWKSTA_INFO_502, *LPWKSTA_INFO_502;

Members

wki502_char_wait
Specifies the number of seconds the computer waits for a remote resource to become available.
wki502_collection_time
Specifies the number of milliseconds the computer collects data before sending the data to a character device resource. The workstation waits the specified time or collects the number of characters specified by the wki502_maximum_collection_count member, whichever comes first.
wki502_maximum_collection_count
Specifies the number of bytes of information the computer collects before sending the data to a character device resource. The workstation collects the specified number of bytes or waits the period of time specified by the wki502_collection_time member, whichever comes first.
wki502_keep_conn
Specifies the number of seconds the server maintains an inactive connection to a server's resource.
wki502_max_cmds
Specifies the number of simultaneous network device driver commands that can be sent to the network.
wki502_sess_timeout
Indicates the number of seconds the server waits before disconnecting an inactive session.
wki502_siz_char_buf
Specifies the maximum size, in bytes, of a character pipe buffer and device buffer.
wki502_max_threads
Specifies the number of threads the computer can dedicate to the network.
wki502_lock_quota
Reserved.
wki502_lock_increment
Reserved.
wki502_lock_maximum
Reserved.
wki502_pipe_increment
Reserved.
wki502_pipe_maximum
Reserved.
wki502_cache_file_timeout
Reserved.
wki502_read_ahead_throughput
Reserved.
wki502_dormant_file_limit
Reserved.
wki502_num_mailslot_buffers
Reserved.
wki502_num_srv_announce_buffers
Reserved.
wki502_max_illegal_datagram_events
Reserved.
wki502_illegal_datagram_event_reset_frequency
Reserved.
wki502_log_election_packets
Reserved.
wki502_use_opportunistic_locking
Reserved.
wki502_use_unlock_behind
Reserved.
wki502_use_close_behind
Reserved.
wki502_buf_named_pipes
Reserved.
wki502_use_lock_read_unlock
Reserved.
wki502_utilize_nt_caching
Reserved.
wki502_use_raw_read
Reserved.
wki502_use_raw_write
Reserved.
wki502_use_write_raw_data
Reserved.
wki502_use_encryption
Reserved.
wki502_buf_files_deny_write
Reserved.
wki502_buf_read_only_files
Reserved.
wki502_force_core_create_mode
Reserved.
wki502_use_512_byte_max_transfer
Reserved.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Workstation and Workstation User Functions, NetWkstaGetInfo, NetWkstaSetInfo


WKSTA_TRANSPORT_INFO_0

The WKSTA_TRANSPORT_INFO_0 structure contains information about the workstation transport protocol, such as Wide Area Network (WAN) or NetBIOS.

typedef struct _WKSTA_TRANSPORT_INFO_0 {
  DWORD     wkti0_quality_of_service;
  DWORD     wkti0_number_of_vcs;
  LPWSTR    wkti0_transport_name;
  LPWSTR    wkti0_transport_address;
  BOOL      wkti0_wan_ish;
}WKSTA_TRANSPORT_INFO_0, *PWKSTA_TRANSPORT_INFO_0, *LPWKSTA_TRANSPORT_INFO_0;

Members

wkti0_quality_of_service
Specifies a value that determines the search order of the transport protocol with respect to other transport protocols. The highest value is searched first.
wkti0_number_of_vcs
Specifies the number of clients communicating with the server using this transport protocol.
wkti0_transport_name
Specifies the device name of the transport protocol.
wkti0_transport_address
Specifies the address of the server on this transport protocol.
wkti0_wan_ish
This member is ignored by the NetWkstaTransportAdd function. For the NetWkstaTransportEnum function, this member indicates whether the transport protocol is a WAN transport protocol. This member is set to TRUE for NetBIOS/TCIP; it is set to FALSE for NetBEUI and NetBIOS/IPX.

Whistler Certain legacy networking protocols, including NetBEUI, will no longer be supported. For more information, see Network Protocol Support in Windows.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Server and Workstation Transport Functions, NetWkstaTransportAdd, NetWkstaTransportEnum


WKSTA_USER_INFO_0

The WKSTA_USER_INFO_0 structure contains the name of the user on a specified workstation.

typedef struct _WKSTA_USER_INFO_0 {
  LPWSTR    wkui0_username;
}WKSTA_USER_INFO_0, *PWKSTA_USER_INFO_0, *LPWKSTA_USER_INFO_0;

Members

wkui0_username
Specifies the name of the user currently logged on to the workstation.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Workstation and Workstation User Functions, NetWkstaUserEnum, NetWkstaUserGetInfo


WKSTA_USER_INFO_1

The WKSTA_USER_INFO_1 structure contains user information as it pertains to a specific workstation. The information includes the name of the current user, the domains accessed by the workstation, and user account information.

typedef struct _WKSTA_USER_INFO_1 {
  LPWSTR    wkui1_username;
  LPWSTR    wkui1_logon_domain;
  LPWSTR    wkui1_oth_domains;
  LPWSTR    wkui1_logon_server;
}WKSTA_USER_INFO_1, *PWKSTA_USER_INFO_1, *LPWKSTA_USER_INFO_1;

Members

wkui1_username
Specifies the name of the user currently logged on to the workstation.
wkui1_logon_domain
Specifies the name of the domain in which the user is currently logged on.
wkui1_oth_domains
Specifies the list of operating system domains browsed by the workstation. The domain names are separated by blanks.
wkui1_logon_server
Specifies the name of the computer that authenticated the server.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Workstation and Workstation User Functions, NetWkstaUserEnum, NetWkstaUserGetInfo, NetWkstaUserSetInfo


WKSTA_USER_INFO_1101

The WKSTA_USER_INFO_1101 structure contains information about the domains accessed by a workstation.

typedef struct _WKSTA_USER_INFO_1101 {
  LPWSTR    wkui1101_oth_domains;
} WKSTA_USER_INFO_1101, *PWKSTA_USER_INFO_1101, *LPWKSTA_USER_INFO_1101;

Members

wkui1101_oth_domains
Specifies the list of operating system domains browsed by the workstation. The domain names are separated by blanks.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmwksta.h; include Lm.h.

See Also

Network Management Overview, Network Management Structures, Workstation and Workstation User Functions, NetWkstaUserGetInfo, NetWkstaUserSetInfo


Network Management Macros

The following macros can be used with network management alert data buffers:

ALERT_OTHER_INFO
ALERT_VAR_DATA

For more information, see the alert functions.


ALERT_OTHER_INFO

The ALERT_OTHER_INFO macro returns a pointer to the alert-specific data in an alert message. The data follows a STD_ALERT structure, and can be an ADMIN_OTHER_INFO, a PRINT_OTHER_INFO, or a USER_OTHER_INFO structure.

ALERT_OTHER_INFO(
  LPBYTE x
);

Parameters

x
Pointer to a STD_ALERT structure that was specified in a call to the NetAlertRaise function.

Return Value

The return value is a pointer to the fixed-length structure that follows the STD_ALERT structure in the alert message.

Remarks

The ALERT_OTHER_INFO macro is defined as follows:

#define ALERT_OTHER_INFO(x)    ((LPBYTE)(x) + sizeof(STD_ALERT))

See NetAlertRaise for a code sample that uses the ALERT_OTHER_INFO macro to retrieve a pointer to the ADMIN_OTHER_INFO structure.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.

See Also

Network Management Overview, Network Management Macros, Alert Functions, ADMIN_OTHER_INFO, PRINT_OTHER_INFO, STD_ALERT, USER_OTHER_INFO, NetAlertRaise, ALERT_VAR_DATA


ALERT_VAR_DATA

The ALERT_VAR_DATA macro returns a pointer to the variable-length portion of an alert message. Variable-length data can follow an ADMIN_OTHER_INFO, a PRINT_OTHER_INFO, or a USER_OTHER_INFO structure.

ALERT_VAR_DATA(
  LPBYTE p
);

Parameters

p
Pointer to an ADMIN_OTHER_INFO, a PRINT_OTHER_INFO, or a USER_OTHER_INFO structure that was specified in a call to the NetAlertRaise function or the NetAlertRaiseEx function.

Return Value

The return value is a pointer to the variable-length data that follows the fixed-length structure in the alert message.

Remarks

The ALERT_VAR_DATA macro is defined as follows:

#define ALERT_VAR_DATA(p)      ((LPBYTE)(p) + sizeof(*p))

See NetAlertRaise and NetAlertRaiseEx for code samples that use the ALERT_VAR_DATA macro to retrieve a pointer to the variable-length data in an alert message.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Unsupported.
Header: Declared in Lmalert.h; include Lm.h.

See Also

Network Management Overview, Network Management Macros, Alert Functions, ADMIN_OTHER_INFO, PRINT_OTHER_INFO, USER_OTHER_INFO, NetAlertRaise, NetAlertRaiseEx, ALERT_OTHER_INFO


Network Management Error Codes

The following table provides a list of error codes for the network management functions.

Code | Description | Name
2102 | The workstation driver is not installed. | NERR_NetNotStarted
2103 | The server could not be located. | NERR_UnknownServer
2104 | An internal error occurred. The network cannot access a shared memory segment. | NERR_ShareMem
2105 | A network resource shortage occurred. | NERR_NoNetworkResource
2106 | This operation is not supported on workstations. | NERR_RemoteOnly
2107 | The device is not connected. | NERR_DevNotRedirected
2114 | The Server service is not started. | NERR_ServerNotStarted
2115 | The queue is empty. | NERR_ItemNotFound
2116 | The device or directory does not exist. | NERR_UnknownDevDir
2117 | The operation is invalid on a redirected resource. | NERR_RedirectedPath
2118 | The name has already been shared. | NERR_DuplicateShare
2119 | The server is currently out of the requested resource. | NERR_NoRoom
2121 | Requested addition of items exceeds the maximum allowed. | NERR_TooManyItems
2122 | The Peer service supports only two simultaneous users. | NERR_InvalidMaxUsers
2123 | The API return buffer is too small. | NERR_BufTooSmall
2127 | A remote API error occurred. | NERR_RemoteErr
2131 | An error occurred when opening or reading the configuration file. | NERR_LanmanIniError
2136 | A general network error occurred. | NERR_NetworkError
2137 | The Workstation service is in an inconsistent state. Restart the computer before restarting the Workstation service. | NERR_WkstaInconsistentState
2138 | The Workstation service has not been started. | NERR_WkstaNotStarted
2139 | The requested information is not available. | NERR_BrowserNotStarted
2140 | An internal error occurred. | NERR_InternalError
2141 | The server is not configured for transactions. | NERR_BadTransactConfig
2142 | The requested API is not supported on the remote server. | NERR_InvalidAPI
2143 | The event name is invalid. | NERR_BadEventName
2144 | The computer name already exists on the network. Change it and restart the computer. | NERR_DupNameReboot
2146 | The specified component could not be found in the configuration information. | NERR_CfgCompNotFound
2147 | The specified parameter could not be found in the configuration information. | NERR_CfgParamNotFound
2149 | A line in the configuration file is too long. | NERR_LineTooLong
2150 | The printer does not exist. | NERR_QNotFound
2151 | The print job does not exist. | NERR_JobNotFound
2152 | The printer destination cannot be found. | NERR_DestNotFound
2153 | The printer destination already exists. | NERR_DestExists
2154 | The printer queue already exists. | NERR_QExists
2155 | No more printers can be added. | NERR_QNoRoom
2156 | No more print jobs can be added. | NERR_JobNoRoom
2157 | No more printer destinations can be added. | NERR_DestNoRoom
2158 | This printer destination is idle and cannot accept control operations. | NERR_DestIdle
2159 | This printer destination request contains an invalid control function. | NERR_DestInvalidOp
2160 | The print processor is not responding. | NERR_ProcNoRespond
2161 | The spooler is not running. | NERR_SpoolerNotLoaded
2162 | This operation cannot be performed on the print destination in its current state. | NERR_DestInvalidState
2163 | This operation cannot be performed on the printer queue in its current state. | NERR_QinvalidState
2164 | This operation cannot be performed on the print job in its current state. | NERR_JobInvalidState
2165 | A spooler memory allocation failure occurred. | NERR_SpoolNoMemory
2166 | The device driver does not exist. | NERR_DriverNotFound
2167 | The data type is not supported by the print processor. | NERR_DataTypeInvalid
2168 | The print processor is not installed. | NERR_ProcNotFound
2180 | The service database is locked. | NERR_ServiceTableLocked
2181 | The service table is full. | NERR_ServiceTableFull
2182 | The requested service has already been started. | NERR_ServiceInstalled
2183 | The service does not respond to control actions. | NERR_ServiceEntryLocked
2184 | The service has not been started. | NERR_ServiceNotInstalled
2185 | The service name is invalid. | NERR_BadServiceName
2186 | The service is not responding to the control function. | NERR_ServiceCtlTimeout
2187 | The service control is busy. | NERR_ServiceCtlBusy
2188 | The configuration file contains an invalid service program name. | NERR_BadServiceProgName
2189 | The service could not be controlled in its present state. | NERR_ServiceNotCtrl
2190 | The service ended abnormally. | NERR_ServiceKillProc
2191 | The requested pause or stop is not valid for this service. | NERR_ServiceCtlNotValid
2192 | The service control dispatcher could not find the service name in the dispatch table. | NERR_NotInDispatchTbl
2193 | The service control dispatcher pipe read failed. | NERR_BadControlRecv
2194 | A thread for the new service could not be created. | NERR_ServiceNotStarting
2200 | This workstation is already logged on to the local-area network. | NERR_AlreadyLoggedOn
2201 | The workstation is not logged on to the local-area network. | NERR_NotLoggedOn
2202 | The user name or group name parameter is invalid. | NERR_BadUsername
2203 | The password parameter is invalid. | NERR_BadPassword
2204 | @W The logon processor did not add the message alias. | NERR_UnableToAddName_W
2205 | The logon processor did not add the message alias. | NERR_UnableToAddName_F
2206 | @W The logoff processor did not delete the message alias. | NERR_UnableToDelName_W
2207 | The logoff processor did not delete the message alias. | NERR_UnableToDelName_F
2209 | Network logons are paused. | NERR_LogonsPaused
2210 | A centralized logon-server conflict occurred. | NERR_LogonServerConflict
2211 | The server is configured without a valid user path. | NERR_LogonNoUserPath
2212 | An error occurred while loading or running the logon script. | NERR_LogonScriptError
2214 | The logon server was not specified. Your computer will be logged on as STANDALONE. | NERR_StandaloneLogon
2215 | The logon server could not be found. | NERR_LogonServerNotFound
2216 | There is already a logon domain for this computer. | NERR_LogonDomainExists
2217 | The logon server could not validate the logon. | NERR_NonValidatedLogon
2219 | The security database could not be found. | NERR_ACFNotFound
2220 | The group name could not be found. | NERR_GroupNotFound
2221 | The user name could not be found. | NERR_UserNotFound
2222 | The resource name could not be found. | NERR_ResourceNotFound
2223 | The group already exists. | NERR_GroupExists
2224 | The user account already exists. | NERR_UserExists
2225 | The resource permission list already exists. | NERR_ResourceExists
2226 | This operation is only allowed on the primary domain controller of the domain. | NERR_NotPrimary
2227 | The security database has not been started. | NERR_ACFNotLoaded
2228 | There are too many names in the user accounts database. | NERR_ACFNoRoom
2229 | A disk I/O failure occurred. | NERR_ACFFileIOFail
2230 | The limit of 64 entries per resource was exceeded. | NERR_ACFTooManyLists
2231 | Deleting a user with a session is not allowed. | NERR_UserLogon
2232 | The parent directory could not be located. | NERR_ACFNoParent
2233 | Unable to add to the security database session cache segment. | NERR_CanNotGrowSegment
2234 | This operation is not allowed on this special group. | NERR_SpeGroupOp
2235 | This user is not cached in user accounts database session cache. | NERR_NotInCache
2236 | The user already belongs to this group. | NERR_UserInGroup
2237 | The user does not belong to this group. | NERR_UserNotInGroup
2238 | This user account is undefined. | NERR_AccountUndefined
2239 | This user account has expired. | NERR_AccountExpired
2240 | The user is not allowed to log on from this workstation. | NERR_InvalidWorkstation
2241 | The user is not allowed to log on at this time. | NERR_InvalidLogonHours
2242 | The password of this user has expired. | NERR_PasswordExpired
2243 | The password of this user cannot change. | NERR_PasswordCantChange
2244 | This password cannot be used now. | NERR_PasswordHistConflict
2245 | The password does not meet the password policy requirements. Check the minimum password length, password complexity and password history requirements. | NERR_PasswordTooShort
2246 | The password of this user is too recent to change. | NERR_PasswordTooRecent
2247 | The security database is corrupted. | NERR_InvalidDatabase
2248 | No updates are necessary to this replicant network/local security database. | NERR_DatabaseUpToDate
2249 | This replicant database is outdated; synchronization is required. | NERR_SyncRequired
2250 | The network connection could not be found. | NERR_UseNotFound
2251 | This asg_type is invalid. | NERR_BadAsgType
2252 | This device is currently being shared. | NERR_DeviceIsShared
2270 | The computer name could not be added as a message alias. The name may already exist on the network. | NERR_NoComputerName
2271 | The Messenger service is already started. | NERR_MsgAlreadyStarted
2272 | The Messenger service failed to start. | NERR_MsgInitFailed
2273 | The message alias could not be found on the network. | NERR_NameNotFound
2274 | This message alias has already been forwarded. | NERR_AlreadyForwarded
2275 | This message alias has been added but is still forwarded. | NERR_AddForwarded
2276 | This message alias already exists locally. | NERR_AlreadyExists
2277 | The maximum number of added message aliases has been exceeded. | NERR_TooManyNames
2278 | The computer name could not be deleted. | NERR_DelComputerName
2279 | Messages cannot be forwarded back to the same workstation. | NERR_LocalForward
2280 | An error occurred in the domain message processor. | NERR_GrpMsgProcessor
2281 | The message was sent, but the recipient has paused the Messenger service. | NERR_PausedRemote
2282 | The message was sent but not received. | NERR_BadReceive
2283 | The message alias is currently in use. Try again later. | NERR_NameInUse
2284 | The Messenger service has not been started. | NERR_MsgNotStarted
2285 | The name is not on the local computer. | NERR_NotLocalName
2286 | The forwarded message alias could not be found on the network. | NERR_NoForwardName
2287 | The message alias table on the remote station is full. | NERR_RemoteFull
2288 | Messages for this alias are not currently being forwarded. | NERR_NameNotForwarded
2289 | The broadcast message was truncated. | NERR_TruncatedBroadcast
2294 | This is an invalid device name. | NERR_InvalidDevice
2295 | A write fault occurred. | NERR_WriteFault
2297 | A duplicate message alias exists on the network. | NERR_DuplicateName
2298 | @W This message alias will be deleted later. | NERR_DeleteLater
2299 | The message alias was not successfully deleted from all networks. | NERR_IncompleteDel
2300 | This operation is not supported on computers with multiple networks. | NERR_MultipleNets
2310 | This shared resource does not exist. | NERR_NetNameNotFound
2311 | This device is not shared. | NERR_DeviceNotShared
2312 | A session does not exist with that computer name. | NERR_ClientNameNotFound
2314 | There is not an open file with that identification number. | NERR_FileIdNotFound
2315 | A failure occurred when executing a remote administration command. | NERR_ExecFailure
2316 | A failure occurred when opening a remote temporary file. | NERR_TmpFile
2317 | The data returned from a remote administration command has been truncated to 64K. | NERR_TooMuchData
2318 | This device cannot be shared as both a spooled and a non-spooled resource. | NERR_DeviceShareConflict
2319 | The information in the list of servers may be incorrect. | NERR_BrowserTableIncomplete
2320 | The computer is not active in this domain. | NERR_NotLocalDomain
2321 | The share must be removed from the Distributed File System before it can be deleted. | NERR_IsDfsShare
2331 | The operation is invalid for this device. | NERR_DevInvalidOpCode
2332 | This device cannot be shared. | NERR_DevNotFound
2333 | This device was not open. | NERR_DevNotOpen
2334 | This device name list is invalid. | NERR_BadQueueDevString
2335 | The queue priority is invalid. | NERR_BadQueuePriority
2337 | There are no shared communication devices. | NERR_NoCommDevs
2338 | The queue you specified does not exist. | NERR_QueueNotFound
2340 | This list of devices is invalid. | NERR_BadDevString
2341 | The requested device is invalid. | NERR_BadDev
2342 | This device is already in use by the spooler. | NERR_InUseBySpooler
2343 | This device is already in use as a communication device. | NERR_CommDevInUse
2351 | This computer name is invalid. | NERR_InvalidComputer
2354 | The string and prefix specified are too long. | NERR_MaxLenExceeded
2356 | This path component is invalid. | NERR_BadComponent
2357 | Could not determine the type of input. | NERR_CantType
2362 | The buffer for types is not big enough. | NERR_TooManyEntries
2370 | Profile files cannot exceed 64K. | NERR_ProfileFileTooBig
2371 | The start offset is out of range. | NERR_ProfileOffset
2372 | The system cannot delete current connections to network resources. | NERR_ProfileCleanup
2373 | The system was unable to parse the command line in this file. | NERR_ProfileUnknownCmd
2374 | An error occurred while loading the profile file. | NERR_ProfileLoadErr
2375 | @W Errors occurred while saving the profile file. The profile was partially saved. | NERR_ProfileSaveErr
2377 | Log file %1 is full. | NERR_LogOverflow
2378 | This log file has changed between reads. | NERR_LogFileChanged
2379 | Log file %1 is corrupt. | NERR_LogFileCorrupt
2380 | The source path cannot be a directory. | NERR_SourceIsDir
2381 | The source path is illegal. | NERR_BadSource
2382 | The destination path is illegal. | NERR_BadDest
2383 | The source and destination paths are on different servers. | NERR_DifferentServers
2385 | The Run server you requested is paused. | NERR_RunSrvPaused
2389 | An error occurred when communicating with a Run server. | NERR_ErrCommRunSrv
2391 | An error occurred when starting a background process. | NERR_ErrorExecingGhost
2392 | The shared resource you are connected to could not be found. | NERR_ShareNotFound
2400 | The LAN adapter number is invalid. | NERR_InvalidLana
2401 | There are open files on the connection. | NERR_OpenFiles
2402 | Active connections still exist. | NERR_ActiveConns
2403 | This share name or password is invalid. | NERR_BadPasswordCore
2404 | The device is being accessed by an active process. | NERR_DevInUse
2405 | The drive letter is in use locally. | NERR_LocalDrive
2430 | The specified client is already registered for the specified event. | NERR_AlertExists
2431 | The alert table is full. | NERR_TooManyAlerts
2432 | An invalid or nonexistent alert name was raised. | NERR_NoSuchAlert
2433 | The alert recipient is invalid. | NERR_BadRecipient
2434 | A user's session with this server has been deleted | NERR_AcctLimitExceeded
2440 | The log file does not contain the requested record number. | NERR_InvalidLogSeek
2450 | The user accounts database is not configured correctly. | NERR_BadUasConfig
2451 | This operation is not permitted when the Netlogon service is running. | NERR_InvalidUASOp
2452 | This operation is not allowed on the last administrative account. | NERR_LastAdmin
2453 | Could not find domain controller for this domain. | NERR_DCNotFound
2454 | Could not set logon information for this user. | NERR_LogonTrackingError
2455 | The Netlogon service has not been started. | NERR_NetlogonNotStarted
2456 | Unable to add to the user accounts database. | NERR_CanNotGrowUASFile
2457 | This server's clock is not synchronized with the primary domain controller's clock. | NERR_TimeDiffAtDC
2458 | A password mismatch has been detected. | NERR_PasswordMismatch
2460 | The server identification does not specify a valid server. | NERR_NoSuchServer
2461 | The session identification does not specify a valid session. | NERR_NoSuchSession
2462 | The connection identification does not specify a valid connection. | NERR_NoSuchConnection
2463 | There is no space for another entry in the table of available servers. | NERR_TooManyServers
2464 | The server has reached the maximum number of sessions it supports. | NERR_TooManySessions
2465 | The server has reached the maximum number of connections it supports. | NERR_TooManyConnections
2466 | The server cannot open more files because it has reached its maximum number. | NERR_TooManyFiles
2467 | There are no alternate servers registered on this server. | NERR_NoAlternateServers
2470 | Try down-level (remote admin protocol) version of API instead. | NERR_TryDownLevel
2480 | The UPS driver could not be accessed by the UPS service. | NERR_UPSDriverNotStarted
2481 | The UPS service is not configured correctly. | NERR_UPSInvalidConfig
2482 | The UPS service could not access the specified Comm Port. | NERR_UPSInvalidCommPort
2483 | The UPS indicated a line fail or low battery situation. Service not started. | NERR_UPSSignalAsserted
2484 | The UPS service failed to perform a system shut down. | NERR_UPSShutdownFailed
2500 | The program below returned an MS-DOS error code: | NERR_BadDosRetCode
2501 | The program below needs more memory: | NERR_ProgNeedsExtraMem
2502 | The program below called an unsupported MS-DOS function: | NERR_BadDosFunction
2503 | The workstation failed to boot. | NERR_RemoteBootFailed
2504 | The file below is corrupt. | NERR_BadFileCheckSum
2505 | No loader is specified in the boot-block definition file. | NERR_NoRplBootSystem
2506 | NetBIOS returned an error: The NCB and SMB are dumped above. | NERR_RplLoadrNetBiosErr
2507 | A disk I/O error occurred. | NERR_RplLoadrDiskErr
2508 | Image parameter substitution failed. | NERR_ImageParamErr
2509 | Too many image parameters cross disk sector boundaries. | NERR_TooManyImageParams
2510 | The image was not generated from an MS-DOS diskette formatted with /S. | NERR_NonDosFloppyUsed
2511 | Remote boot will be restarted later. | NERR_RplBootRestart
2512 | The call to the Remoteboot server failed. | NERR_RplSrvrCallFailed
2513 | Cannot connect to the Remoteboot server. | NERR_CantConnectRplSrvr
2514 | Cannot open image file on the Remoteboot server. | NERR_CantOpenImageFile
2515 | Connecting to the Remoteboot server... | NERR_CallingRplSrvr
2516 | Connecting to the Remoteboot server... | NERR_StartingRplBoot
2517 | Remote boot service was stopped; check the error log for the cause of the problem. | NERR_RplBootServiceTerm
2518 | Remote boot startup failed; check the error log for the cause of the problem. | NERR_RplBootStartFailed
2519 | A second connection to a Remoteboot resource is not allowed. | NERR_RPL_CONNECTED
2550 | The browser service was configured with MaintainServerList=No. | NERR_BrowserConfiguredToNotRun
2610 | Service failed to start since none of the network adapters started with this service. | NERR_RplNoAdaptersStarted
2611 | Service failed to start due to bad startup information in the registry. | NERR_RplBadRegistry
2612 | Service failed to start because its database is absent or corrupt. | NERR_RplBadDatabase
2613 | Service failed to start because RPLFILES share is absent. | NERR_RplRplfilesShare
2614 | Service failed to start because RPLUSER group is absent. | NERR_RplNotRplServer
2615 | Cannot enumerate service records. | NERR_RplCannotEnum
2616 | Workstation record information has been corrupted. | NERR_RplWkstaInfoCorrupted
2617 | Workstation record was not found. | NERR_RplWkstaNotFound
2618 | Workstation name is in use by some other workstation. | NERR_RplWkstaNameUnavailable
2619 | Profile record information has been corrupted. | NERR_RplProfileInfoCorrupted
2620 | Profile record was not found. | NERR_RplProfileNotFound
2621 | Profile name is in use by some other profile. | NERR_RplProfileNameUnavailable
2622 | There are workstations using this profile. | NERR_RplProfileNotEmpty
2623 | Configuration record information has been corrupted. | NERR_RplConfigInfoCorrupted
2624 | Configuration record was not found. | NERR_RplConfigNotFound
2625 | Adapter id record information has been corrupted. | NERR_RplAdapterInfoCorrupted
2626 | An internal service error has occurred. | NERR_RplInternal
2627 | Vendor id record information has been corrupted. | NERR_RplVendorInfoCorrupted
2628 | Boot block record information has been corrupted. | NERR_RplBootInfoCorrupted
2629 | The user account for this workstation record is missing. | NERR_RplWkstaNeedsUserAcct
2630 | The RPLUSER local group could not be found. | NERR_RplNeedsRPLUSERAcct
2631 | Boot block record was not found. | NERR_RplBootNotFound
2632 | Chosen profile is incompatible with this workstation. | NERR_RplIncompatibleProfile
2633 | Chosen network adapter id is in use by some other workstation. | NERR_RplAdapterNameUnavailable
2634 | There are profiles using this configuration. | NERR_RplConfigNotEmpty
2635 | There are workstations, profiles, or configurations using this boot block. | NERR_RplBootInUse
2636 | Service failed to backup Remoteboot database. | NERR_RplBackupDatabase
2637 | Adapter record was not found. | NERR_RplAdapterNotFound
2638 | Vendor record was not found. | NERR_RplVendorNotFound
2639 | Vendor name is in use by some other vendor record. | NERR_RplVendorNameUnavailable
2640 | (boot name, vendor id) is in use by some other boot block record. | NERR_RplBootNameUnavailable
2641 | Configuration name is in use by some other configuration. | NERR_RplConfigNameUnavailable
2660 | The internal database maintained by the Dfs service is corrupt | NERR_DfsInternalCorruption
2661 | One of the records in the internal Dfs database is corrupt | NERR_DfsVolumeDataCorrupt
2662 | There is no volume whose entry path matches the input Entry Path | NERR_DfsNoSuchVolume
2663 | A volume with the given name already exists | NERR_DfsVolumeAlreadyExists
2664 | The server share specified is already shared in the Dfs | NERR_DfsAlreadyShared
2665 | The indicated server share does not support the indicated Dfs volume | NERR_DfsNoSuchShare
2666 | The operation is not valid on a non-leaf volume | NERR_DfsNotALeafVolume
2667 | The operation is not valid on a leaf volume | NERR_DfsLeafVolume
2668 | The operation is ambiguous because the volume has multiple servers | NERR_DfsVolumeHasMultipleServers
2669 | Unable to create a junction point | NERR_DfsCantCreateJunctionPoint
2670 | The server is not Dfs Aware | NERR_DfsServerNotDfsAware
2671 | The specified rename target path is invalid | NERR_DfsBadRenamePath
2672 | The specified Dfs volume is offline | NERR_DfsVolumeIsOffline
2673 | The specified server is not a server for this volume | NERR_DfsNoSuchServer
2674 | A cycle in the Dfs name was detected | NERR_DfsCyclicalName
2675 | The operation is not supported on a server-based Dfs | NERR_DfsNotSupportedInServerDfs
2676 | This volume is already supported by the specified server-share. | NERR_DfsDuplicateService
2677 | Can't remove the last server-share supporting this volume. | NERR_DfsCantRemoveLastServerShare
2678 | The operation is not supported for an Inter-Dfs volume. | NERR_DfsVolumeIsInterDfs
2679 | The internal state of the Dfs Service has become inconsistent. | NERR_DfsInconsistent
2680 | The Dfs Service has been installed on the specified server. | NERR_DfsServerUpgraded
2681 | The Dfs data being reconciled is identical. | NERR_DfsDataIsIdentical
2682 | The Dfs root volume cannot be deleted - Uninstall Dfs if required. | NERR_DfsCantRemoveDfsRoot
2683 | A child or parent directory of the share is already in a Dfs. | NERR_DfsChildOrParentInDfs
2690 | Dfs internal error | NERR_DfsInternalError
2691 | This machine is already joined to a domain. | NERR_SetupAlreadyJoined
2692 | This machine is not currently joined to a domain. | NERR_SetupNotJoined
2693 | This machine is a domain controller and cannot be unjoined from a domain. | NERR_SetupDomainController
2694 | The destination domain controller does not support creating machine accounts in OUs. | NERR_DefaultJoinRequired
2695 | The specified workgroup name is invalid. | NERR_InvalidWorkgroupName
2696 | The specified computer name is incompatible with the default language used on the domain controller. | NERR_NameUsesIncompatibleCodePage
2697 | The specified computer account could not be found. | NERR_ComputerAccountNotFound


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.