Do not remove any of the division marks (:::) in this template. They control the basic layout of the document, including the way page numbers are printed.
{TOC \o|1. Overview 3
2. API buffers 3
2.1. API Data Alignment 4
2.2. Enumeration Buffer Lengths 4
2.3. Parameter Error Reporting 4
2.4. Parmnum For SetInfo 4
2.5. Parmnum For GetInfo 4
2.6. Embedded Strings 5
2.7. Enumeration Resume Handles 5
2.8. User-specific information 5
2.9. Enumeration APIs 5
2.10. SetInfo APIs 6
3. Windows Networking APIs 6
3.1. API Status 6
3.2. RPC Buffer Allocation Errors 6
3.3. Obsolete Information Fields 6
3.4. NLS Support 7
4. Windows Networking API Definitions. 7
4.1. Buffer Manipulation APIs. 7
4.1.1. NetApiBufferAllocate 7
4.1.2. NetApiBufferFree 7
4.1.3. NetApiBufferReallocate 8
4.1.4. NetApiBufferSize 8
4.2. Service APIs. 8
4.2.1. NetServiceControl 9
4.2.2. NetServiceEnum 10
4.2.3. NetServiceGetInfo 11
4.2.4. NetServiceInstall 12
4.3. Server APIs 13
4.3.1. NetServerEnum 20
4.3.2. NetServerGetInfo 21
4.3.3. NetServerSetInfo 22
4.3.4. NetServerDiskEnum 23
4.4. Workstation and WorkstationUser APIs 24
4.4.1. NetWkstaGetInfo 32
4.4.2. NetWkstaSetInfo 32
4.4.3. NetWkstaUserGetInfo 33
4.4.4. NetWkstaUserSetInfo 34
4.4.5. NetWkstaUserEnum 34
4.5. Use APIs 35
4.5.1. NetUseAdd 37
4.5.2. NetUseDel 37
4.5.3. NetUseEnum 38
4.5.4. NetUseGetInfo 39
4.6. Share APIs 39
4.6.1. NetShareAdd 41
4.6.2. NetShareEnum 42
4.6.3. NetShareGetInfo 43
4.6.4. NetShareSetInfo 43
4.6.5. NetShareDel 44
4.6.6. NetShareCheck 45
4.7. Session 45
4.7.1. NetSessionEnum 46
4.7.2. NetSessionGetInfo 48
4.7.3. NetSessionDel 48
4.8. Connection APIs 49
4.8.1. NetConnectionEnum 50
4.9. File APIs 51
4.9.1. NetFileEnum 52
4.9.2. NetFileGetInfo 53
4.9.3. NetFileClose 54
4.10. Message APIs 54
4.10.1. NetMessageNameAdd 55
4.10.2. NetMessageNameEnum 55
4.10.3. NetMessageNameGetInfo 56
4.10.4. NetMessageNameDel 57
4.10.5. NetMessageBufferSend 57
4.11. Remote Utility API 58
4.11.1. NetRemoteTOD API 58
4.12. Security Account APIs 59
4.12.1. User APIs 59
4.12.1.1. NetUserAdd 65
4.12.1.2. NetUserEnum 66
4.12.1.3. NetUserGetInfo 67
4.12.1.4. NetUserSetInfo 68
4.12.1.5. NetUserDel 68
4.12.1.6. NetUserGetGroups 69
4.12.1.7. NetUserGetLocalGroups 70
4.12.1.8. NetUserSetGroups 71
4.12.2. User Modal APIS 72
4.12.2.1. NetUserModalsGet 73
4.12.2.2. NetUserModalsSet 74
4.12.3. Global Group APIs 74
4.12.3.1. NetGroupAdd 76
4.12.3.2. NetGroupAddUser 77
4.12.3.3. NetGroupEnum 77
4.12.3.4. NetGroupGetInfo 78
4.12.3.5. NetGroupSetInfo 79
4.12.3.6. NetGroupDel 80
4.12.3.7. NetGroupDelUser 80
4.12.3.8. NetGroupGetUsers 81
4.12.3.9. NetGroupSetUsers 82
4.12.4. Local Group APIs 83
4.12.4.1. NetLocalGroupAdd 84
4.12.4.2. NetLocalGroupAddMember 85
4.12.4.3. NetLocalGroupEnum 86
4.12.4.4. NetLocalGroupGetInfo 87
4.12.4.5. NetLocalGroupSetInfo 87
4.12.4.6. NetLocalGroupDel 88
4.12.4.7. NetLocalGroupDelMember 89
4.12.4.8. NetLocalGroupGetMembers 89
4.12.4.9. NetLocalGroupSetMembers 90
4.12.5. Access APIs 91
4.12.5.1. NetAccessAdd 93
4.12.5.2. NetAccessEnum 94
4.12.5.3. NetAccessGetInfo 95
4.12.5.4. NetAccessSetInfo 96
4.12.5.5. NetAccessDel 97
4.12.5.6. NetAccessGetUserPerms 97
4.12.5.7. NetAccessCheck 98
4.13. Domain APIs 99
4.13.1. NetGetDCName 99
4.14. Transport APIs 100
4.14.1. NetServerTransportAdd 101
4.14.2. NetServerTransportDel 101
4.14.3. NetServerTransportEnum 102
4.14.4. NetWkstaTransportAdd 103
4.14.5. NetWkstaTransportDel 103
4.14.6. NetWkstaTransportEnum 104
4.15. Alert APIs 105
4.15.1. NetAlertRaise 106
4.15.2. NetAlertRaiseEx 107
4.16. Error Logging APIs 107
4.16.1. NetErrorLogClear 109
4.16.2. NetErrorLogRead 109
4.17. Configuration APIs 111
4.17.1. NetConfigGet 111
4.17.2. NetConfigGetAll 112
4.17.3. NetConfigSet 112
4.18. Statistics APIs 113
4.18.1. NetStatisticsGet 116
4.19. Auditing APIs 117
Variable-Length Data 119
4.19.1. NetAuditClear 123
4.19.2. NetAuditRead 124
4.19.3. NetAuditWrite 126
4.20. Replicator APIs 127
4.20.1. Replicator Configuration APIs 127
4.20.1.1. NetReplGetInfo 129
4.20.2. NetReplSetInfo 130
4.20.3. Replicator Export Directory APIs 130
4.20.3.1. NetReplExportDirAdd 132
4.20.4. NetReplExportDirDel 132
4.20.5. NetReplExportDirEnum 133
4.20.6. NetReplExportDirGetInfo 134
4.20.7. NetReplExportDirSetInfo 135
4.20.7.1. NetReplExportDirLock 135
4.20.7.2. NetReplExportDirUnlock 136
4.20.8. Replicator Import Directory APIs 137
4.20.8.1. NetReplImportDirAdd 138
4.20.9. NetReplImportDirDel 139
4.20.10. NetReplImportDirEnum 139
4.20.11. NetReplImportDirGetInfo 140
4.20.11.1. NetReplImportDirLock 141
4.20.11.2. NetReplImportDirUnlock 142
5. Lanman APIs That Are Not Supported In Windows NT 142
5.1. APIs with no 32 bit Net equivalents 143
5.2. APIs that only have support for remoting to downlevel 143
6. Interoperabilty Considerations 143
6.1. Requests From 16-bit LANMan Clients 143
6.2. Calling 16-bit LANMan Servers 144
7. Change History 146
}.End Table C.
1. Overview
For OS/2 based servers the LANMan APIs provided much of the functionality required for a network operating system which was missing from the local operating system. The Windows NT operating system will provide this missing set of functionality in the base. However, in order to make the migration of existing 16-bit applications as easy as possible, it is necessary to still define 32-bit equivalents of some of the LANMan APIs.
The Windows Networking APIs specified in this document are a private set of APIs designed to provide some of the API functionality that was available in LANManager 2.x. They are not the public Windows NT networking APIs. Windows NT takes some of the functionality that was previously supplied by the networking software, and moves this into the base APIs (e.g. error and audit logging, printing). Windows NT also provides a network independent set of network APIs (the WNet APIs) that allow network api's to work across different network vendors' products. If a base API or WNet API exists that could be used by your application, you should convert from the Windows networking API to the public Windows NT equivalent. There are at least three reasons to make the change now:
1.1. The WNet APIs are network independent, while the Windows networking APIs only work on LANManager networks.
1.2. The Windows networking APIs specified in this document may not be supported in future releases on Windows NT. They are provided as a interim set of APIs to assist in the porting of LANManager applications.
1.3. The Windows Networking APIs, as they are not part of the public Win32 API set, have not received the rigorous testing that the Win32 APIs have. They have been tested only by their usage internally.
In this specification, equivalent Win32 APIs will be listed that could be used in place of the Windows networking API. If at all possible, this is the API that your application should use.
This spec assumes that the reader is familiar with the existing set of 16-bit LANMan APIs. The 32-bit widening of the API data structures is specified here but the description of the functionality for each field is not covered unless the functionality has changed from that specified in the LANMAN 2.x Programmer's Reference.
2. API buffers
The RPC runtimes will allocate the buffers required to remote the APIs. This is a requirement for both efficiency and interoperability. Using the RPC runtimes to allocate the API transmission buffers results in the two significant differences between a LANMan 2.x API and windows networking API.
o For a set type API (data to the server) the API caller specifies a buffer containing the info structure relevant to the API level but does not specify the buffer length.
o For a get type API (data returned from the server) the caller does not pre-allocate a buffer for the return information. The caller passes a LPBYTE * to the API on input. On successful return the buffer pointer will contain a pointer to a buffer containing the return information. When the caller has finished processing the returned information NetApiBufferFree must be called. This simplifies the calling code as the caller does not need to guess at the size of the buffer required and will not need to resize and reissue the API as was the case with the LANMan 2.x APIs.
2.1. API Data Alignment
All data structures specified for the Windows networking APIs will be 32-bit word aligned. The base size for an API structure element will be a DWORD.
2.2. Enumeration Buffer Lengths
Enumeration APIs will take an advisory maximum data length parameter, prefmaxlen, which allows a control on the number of bytes returned from an enumeration call. The prefered length is specified in units of 8-bit bytes. The actual API may return more than the prefered maximum length.
A Windows networking API ennumeration call will not return partial entries.
2.3. Parameter Error Reporting
Add and SetInfo APIs will 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 API. For remoted APIs to downlevel servers this field will be returned as PARM_ERROR_UNKNOWN by the RpcXlate conversion layer.
2.4. Parmnum For SetInfo
In order to reduce the number of RPC interfaces we need for each SetInfo API, there will be no Parmnum parameter for the 32-bit SetInfo APIs. Instead, the fields that can be set in the information structures will be set using additional infolevels. Although this will increase the number of infolevels for a given API, it will be easier to program to them. In an attempt to keep the mapping to and from downlevel calls simple, the new infolevels will be easily mapped to the old parmnum values (by subtracting a specific number i.e. PARMNUM_BASE_INFOLEVEL (whose value will be 1000)).
2.5. Parmnum For GetInfo
There will be no addition of a parmnum field for the GetInfo API.
2.6. Embedded Strings
Windows networking API info structures will not contain embedded strings. This improves the alignability of the info structures and allows for OEM flexibility in the core APIs. This does not change the feel of the LANMan 2.x APIs which support string pointers. Code porting merely requires a pointer assignment rather than a string copy.
Any API 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 where the string will not fit as with LANMan 2.x.
2.7. Enumeration Resume Handles
Enumeration resume handles will be identifiers for the actual resume key contained in the instance data for the API. This is required for security, interoperabilty and to simplify the caller code for the API.
If a NULL is passed for the pointer to the resume handle, then no handle is stored and the ennumeration search cannot be continued. This is useful in cases where the application does not want to ennumerate 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, i.e. the enumeration should be restarted from the beginning.
2.8. User-specific information
The LANMan 2.x APIs assumed that there would only be one user per machine. Therefore, some APIs have that assumption built in, e.g. the NetSession APIs. Since this assumption is not valid on NT, the APIs have had to be modified to take a user name as an additional parameter in order to be able to uniquely identify the information being queried or set.
2.9. Enumeration APIs
The enumeration APIs all return the number of entries read, the total entries that could have been returned if the buffer was big enough, a buffer with the entries, and a return code. The following table details what an application can expect for the various parameters (M is less than N):
The caller must first examine the returned status before proceeding to examine any of the other parameters for data.
Note that "totalentries" is the total number of entries that would have been returned if the return buffer was big enough - i.e. the total number of entries that were available for entries, using the current resume handle, if any, when the API was called.
2.10. SetInfo APIs
All the SetInfo APIs take a structure that contains the new information to be set. If any of the pointer fields in the structure are NULL pointers, then the corresponding field is not changed by the call. This is consistent with LANMan 2.x functionality.
In addition, the infolevels that allow GUEST access to query information do not allow callers with GUEST access to set the fields, i.e. a caller with GUEST that calls the SetInfo API will probably get an error back from the SetInfo call.
3. Windows Networking APIs
3.1. API Status
Windows networking APIs will use the LANMan 2.x error reporting convention, i.e. a successful API call returns 0, a non-zero return code indicates an error in the range of the LANMan 2.x API/OS2 errors.
An extended error range will be added for NT specific errors.
Since the Windows networking APIs will use RPC the API error definition will also be extended to include RPC error codes.
3.2. RPC Buffer Allocation Errors
Since the RPC runtime will allocate memory for send and receive buffers the API should expect to see RPC allocation errors. In the event of an RPC allocation error a resumable API handle is invalidated. This is a requirement since resumable APIs are not rewindable.
3.3. Obsolete Information Fields
Many of the information fields in the core API information structures will be obsolescent in the NT service implementation. These fields will remain in the information structure for level compatibility and will be returned with an intelligent default on NT systems.
3.4. NLS Support
There are only UNICODE versions of the Windows networking APIs. If you use these APIs you MUST define UNICODE in your source file prior to including any of the LM include files.
4. Windows Networking API Definitions.
The WIndows Networking APIs are 'stdcall' calling convention functions which return a DWORD API status;
#define NET_API_STATUS DWORD
#define NET_API_FUNCTION __stdcall
4.1. Buffer Manipulation APIs.
For remotable APIs which return information to the caller the RPC runtime will allocate the buffer containg the return information. When the caller has completed processing the returned information NetApiBufferFree must be called. Additional buffer manipulation functions are also supported.
4.1.1. NetApiBufferAllocate
NetApiBufferAllocate allocates ByteCount bytes of memory from the heap.
NET_API_STATUS NET_API_FUNCTION
NetApiBufferAllocate (
IN DWORD ByteCount,
IN LPBYTE * buffer
);
Parameters:
ByteCount __The number of bytes to allocate.
buffer __A pointer to the location to store the pointer to the allocated buffer.
4.1.2. NetApiBufferFree
NetApiBufferFree frees the memory allocated by NetApiBufferAllocate.
NET_API_STATUS NET_API_FUNCTION
NetApiBufferFree (IN LPVOID buffer
);
Parameters:
buffer __A pointer to an API information buffer previously returned on an API call.
4.1.3. NetApiBufferReallocate
NetApiBufferReallocate changes the size of a buffer allocated with NetApiBufferAllocate.
NET_API_STATUS NET_API_FUNCTION
NetApiBufferReallocate (
IN LPVOID OldBuffer,
IN DWORD NewByteCount,
IN LPVOID buffer
);
Parameters:
OldBuffer __A pointer to the buffer to reallocate.
NewByteCount __The new size of the buffer.
buffer __A pointer to an API information buffer previously returned on an API call.
4.1.4. NetApiBufferSize
NetApiBufferSize returns the size in bytes of the buffer allocated via NetApiBufferAllocate.
NET_API_STATUS NET_API_FUNCTION
NetApiBufferSize (
IN LPVOID buffer,
OUT DWORD ByteCount
);
Parameters:
buffer __A pointer to an API information buffer previously returned on an API call.
ByteCount __The size of the buffer.
4.2. Service APIs.
A complete set of Service APIs are provided in the Win32 API set. These should be used in place of the NetService APIs, unless you have a requirement to control services on a downlevel server. See the Services overview in WinHelp for more details.
Service API functions control services. A service is an application that an administrator can control using the Service Controller interfaces.
Services allow administrators to control applications on the network and maintain the integrity of users' data. On a typical network, applications are shared by many users. If an administrator terminates an application running on a server, a user who has not finished working with that application can lose important data. When an application is implemented as a service, the service controller checks the status before changing the state of the service. NT Networking provides several standard services, such as the Workstation, Server, and Messenger services.
A service can be started using the Service API functions. At startup time, the service defines whether it can be stopped, paused, and continued.
NetServiceControl controls the operations of network services, and it can provide time hints to controlling applications. NetServiceEnum retrieves information about all started services. NetServiceGetInfo retrieves information about a particular started service. NetServiceInstall starts a network service. NetServiceStatus sets status and code information for a network service.
The service APIs provide service information at three levels:
NetServiceControl controls the operations of network services.
Privilege Level
Admin privilege. Power User or Server Operator privilege is required to successfully execute NetServiceControl unless the opcode is SERVICE_CTRL_INTERROGATE. In this case, no special privilege is required.
NET_API_STATUS NET_API_FUNCTION
NetServiceControl (
IN LPWSTR servername OPTIONAL,
IN LPWSTR service,
IN DWORD opcode,
IN DWORD arg,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
service __A pointer to an UNICODE string containing the name of the service to receive the control command.
opcode __Control code to send to service
SERVICE_CTRL_INTERROGATE Obtain the status of the service
SERVICE_CTRL_PAUSE Pause the service
SERVICE_CTRL_CONTINUE Continue the paused service
SERVICE_CTRL_UNINSTALL Stop the service
arg __Service specific contol argument to send to service
bufptr __A pointer to the return information structure is returned in the address pointed to by bufptr.
4.2.2. NetServiceEnum
NetServiceEnum retrieves information about all started services, including paused services.
Privilege Level
No special privilege level is required to successfully execute NetServiceEnum.
NET_API_STATUS NET_API_FUNCTION
NetServiceEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required, 0, 1 and 2 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing service 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..
4.2.3. NetServiceGetInfo
NetServiceGetInfo retrieves information about a particular started service.
Privilege Level
No special privilege level is required to successfully execute NetServiceGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetServiceGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR service,
IN DWORD level,
OUT LPBYTE * bufptr,
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
service __A pointer to an UNICODE string containing the name of the service.
level __Level of information required. 0, 1 and 2 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.2.4. NetServiceInstall
NetServiceInstall starts a network service.
Privilege Level
Admin privilege. Power User or Server Operator privilege is required to successfully execute NetServiceInstall.
NET_API_STATUS NET_API_FUNCTION
NetServiceInstall (
IN LPWSTR servername OPTIONAL,
IN LPWSTR service,
IN DWORD argc,
IN LPWSTR argv[],
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
service __A pointer to an UNICODE string containing the name of the service to start.
bufptr __On return a pointer to a SERVICE_INFO_2 structure is returned in the address pointed to by bufptr.
cmdargs __A pointer to a set of command line arguments to pass to the starting service as command line arguments.
4.3. Server APIs
Server API functions perform administrative tasks on a local or remote server. Any user or application with admin privilege on a local or remote server can perform administrative tasks on that server to control its operation, user access, and resource sharing. The low-level parameters that affect a server's operation can be examined and modified by calling NetServerGetInfo and NetServerSetInfo.
The LANMan 2.x server API included several fields which logically belong to other LANMan services and core NT components. For this reason the server information levels available in LANMan 2.x are no longer available in Windows networking APIs. The server specific information is available in 3 levels starting at base level 100.
For NetServerSetInfo, parmnum values refer to the fields in the _SERVER_INFO structures as follows. These values are used when indicating an error in a specific parameter via parm_err.
Use the WNetEnumResource Win32 API if the information you require is returned by it. The WNetEnumResource will return the type (disk, printer, ...), name and comment for a server.
NetServerEnum lists all servers of the specified type(s) that are visible in the specified domain(s). For example, an application can call NetServerEnum to list all domain controllers only or all SQL servers only.
Privilege Level
No special privilege level is required to successfully execute NetServerEnum.
NET_API_STATUS NET_API_FUNCTION
NetServerEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN DWORD servertype,
IN LPWSTR domain,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 100 and 101 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
servertype __A DWORD mask which filters server entries to return from the enumeration. The defines mask bits are:
SV_TYPE_WORKSTATION 0x00000001 All LAN Manager workstation
SV_TYPE_SERVER 0x00000002 All LAN Manager server
SV_TYPE_SQLSERVER 0x00000004 Any server running with SQL server
SV_TYPE_TIMESOURCE 0x00000020 Server running the timesource service
SV_TYPE_AFP 0x00000040 Apple File Protocol servers
SV_TYPE_NOVELL 0x00000080 Novell servers
SV_TYPE_DOMAIN_MEMBER 0x00000100 Domain Member
SV_TYPE_PRINT 0x00000200 Server sharing print queue
SV_TYPE_DIALIN 0x00000400 Server running dialin service.
SV_TYPE_XENIX_SERVER 0x00000800 Xenix server
SV_TYPE_NT 0x00001000 NT server
SV_TYPE_WFW 0x00002000 Server running Windows for Workgroups
SV_TYPE_POTENTIAL_BROWSER 0x00010000 Server that can run the browser service
SV_TYPE_BACKUP_BROWSER 0x00020000 Server running a browser service as backup
SV_TYPE_MASTER_BROWSER 0x00040000 Server running the master browser service
SV_TYPE_DOMAIN_MASTER 0x00080000 Server running the domain master browser
SV_TYPE_ALL 0xffffffff All servers
domain __A pointer to an UNICODE string containing the name of the domain for which a list of servers is to returned. The domain must be the primary domain, one of the other domains for the workstation or the logon domain.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing server 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..
4.3.2. NetServerGetInfo
NetServerGetInfo retrieves information about the specified server.
Privilege Level
Admin privilege or accounts, comm, print, or server operator privilege is required to successfully execute NetServerGetInfo at level 102 or higher. No special privilege is required for level 100 or level 101 calls.
NET_API_STATUS NET_API_FUNCTION
NetServerGetInfo (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 100, 101 and 102 are valid for all platforms. 302, 402, 403, 502 are valid for the appropriate platform.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.3.3. NetServerSetInfo
NetServerSetInfo sets a server's operating parameters; it can set them individually or collectively. This information is stored such that it remains in effect after the system has been reinitialized.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetServerSetInfo.
NET_API_STATUS NET_API_FUNCTION
NetServerSetInfo (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information to set. 100, 101 and 102 are valid for all platforms. 302, 402, 403, 502 are valid for the appropriate platform. In addition, 1001 - 1006, 1009 - 1011, 1016 - 1018, 1021, 1022, 1028, 1029, 1037 - 1043 are valid based on the restrictions for downlevel systems described above.
buf __A pointer to a buffer containing the server information.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.3.4. NetServerDiskEnum
NetServerDiskEnum retrieves a list of disk drives on a server.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetServerDiskEnum on a remote computer. No special privilege is required for local calls.
NET_API_STATUS NET_API_FUNCTION
NetServerDiskEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 0 is the only valid level.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and 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 resumehandle is NULL, then no resume handle is stored..
4.4. Workstation and WorkstationUser APIs
Wksta API functions perform administrative tasks on a local or remote workstation. Any user or application with admin privilege on a local or remote server can perform administrative tasks on that workstation to control its operation, user access, and resource sharing. The low-level parameters that affect a workstation's operation can be examined and modified by calling NetWkstaGetInfo and NetWkstaSetInfo.
The workstation API data structures are restructured from those of LANMan 2.x to allow the information to be grouped by type and privilege. The LANMan 2.x workstation information format is discontinued due to the following problems:
o The base level (0 and 1) were not grouped by accessibility such that a non superset level (level 10) was required to allow guest access to the information.
o 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 grew the size of the information structures unneccessarily, making the API cumbersome to use.
The workstation APIs allow access to two discrete groups of workstation information:
o System information.
o Platform specific information (NT, OS/2, DOS, etc.)
The WkstaUser APIs 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.
Within each group the fields are categorized by security access such that the guest accessible fields are a subset of the user accessible fields which are a subset of the admin accessible fields.
The system information structure contains a platform base number which identifies the levels and format of the platform specific information structures.
This format of workstation information allows for a more logical future extension. When new information is to be added to any set of guest,user and admin information a new set of levels is created to include the current infromation plus the new information.
The following infolevels are only valid for NetWkstaSetInfo and replace the older way of passing in a Parmnum to set a specific field.
The following are supported on downlevel systems (i.e. LANMan 2.x) as well:
For NetWkstaSetInfo, parmnum values refer to the fields in the wksta_info structure as follows. These values are used when indicating an error in a specific parameter via parm_err.
NetWkstaGetInfo returns information about the configuration elements for a workstation.
Privilege Level
Privilege requirements are described with the data structures for the infolevels above.
NET_API_STATUS NET_API_FUNCTION
NetWkstaGetInfo (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 100, 101, 102, 302, 402 and 502 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.4.2. NetWkstaSetInfo
NetWkstaSetInfo configures a workstation. This information is stored such that it remains in effect after the system has been reinitialized.
Privilege Level
Admin privilege is required to successfully execute NetWkstaSetInfo.
NET_API_STATUS NET_API_FUNCTION
NetWkstaSetInfo (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information to set. 100, 101, 102, 201, 202, 302, 402, and 502 are valid. In addition, 1010 - 1013, 1018, 1023, 1027, 1028, 1032, 1033, 1035, and 1041-1062 are valid based on the restrictions mentioned above.
buf __A pointer to a buffer containing the wksta information.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
The WkstaUser APIs are:
4.4.3. NetWkstaUserGetInfo
NetWkstaUserGetInfo returns the user-specific information about the configuration elements for a workstation.
Privilege Level
Privilege requirements are described with the data structures for the infolevels above. This API only works locally.
NET_API_STATUS NET_API_FUNCTION
NetWkstaUserGetInfo (
IN LPWSTR reserved,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
reserved __This field must be set to zero.
level __Level of information required. 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.4.4. NetWkstaUserSetInfo
NetWkstaUserSetInfo sets the user-specific information about the configuration elements for a workstation.
Privilege Level
Privilege requirements are described with the data structures for the infolevels above. This API only works locally.
NET_API_STATUS NET_API_FUNCTION
NetWkstaUserSetInfo (
IN LPWSTR reserved,
IN DWORD level,
OUT LPBYTE * bufptr.
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
reserved __This field must be set to zero.
level __Level of information required. 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.4.5. NetWkstaUserEnum
NetWkstaUserEnum lists information about all current users on the workstation.
Privilege Level
Admin privilege is required to successfully execute NetWkstaUserEnum both locally and on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetWkstaUserEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information provided. Must be 0 or 1.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and 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, then no resume handle is stored..
4.5. Use APIs
The WNetAddConnection(2) and WNetCancelConnection(2) APIs should be used instead of the NetUse APIs.
Use API functions examine or control connections (uses) between workstations and servers. 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 further connections between the workstation and the server are part of this same session until the session ends. Two types of connections can be made: devicename 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 NetUse API are local only, since a connection set up by a remote user would not be accessible to any other users, even the user that was interactively logged onto that machine.
NetUseAdd creates a devicename connection or an explicit UNC connection. Implicit UNC connections are made by the function responsible for the connection.
NetUseAdd establishes an explicit connection between the local computer and a resource shared on a server by redirecting a local devicename to the sharename of a remote server resource (\\servername\sharename). Once a devicename connection is made, users or applications can use the remote resource by specifying the local devicename. To establish an implicit UNC connection, an application passes the sharename of a resource to any function that accepts UNC pathnames.. The function accepts the UNC name and makes a connection to the specified sharename. All further requests on this connection require the full sharename.
NetUseDel ends a connection to a shared resource. NetUseEnum enumerates all current connections between the local computer and resources on remote servers. NetUseGetInfo returns information about a connection to a shared resource.
The Use APIs are available at three information levels.
typedef struct _USE_INFO_0 {
LPWSTR ui0_local;
LPWSTR ui0_remote;
} USE_INFO_0, *PUSE_INFO_0, *LPUSE_INFO_0;
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;
Infolevel 2 is not available if the API is remoted to a downlevel system - ERROR_NOT_SUPPORTED will be returned in that case.
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;
The use APIs are:
4.5.1. NetUseAdd
WNetAddConnection(2) should be used in place of NetUseAdd.
NetUseAdd establishes a connection between a local or NULL devicename and a shared resource by redirecting the local or NULL (UNC) devicename to the shared resource.
NET_API_STATUS NET_API_FUNCTION
NetUseAdd (
IN LPWSTR reserved OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
reserved __Must be NULL.
level __Level of information to set. 1 and 2 are valid.
buf __A pointer to a buffer containing the use information structure.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.5.2. NetUseDel
WNetCancelConnection(2) should be used in place of NetUseDel.
NetUseDel ends a connection to a shared resource.
Privilege Level
This API cannot be executed on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetUseDel (
IN LPWSTR reserved OPTIONAL,
IN LPWSTR usename,
IN DWORD ucond
);
Parameters:
reserved __Must be NULL.
usename __A pointer to an UNICODE string containing the path of the use to delete.
ucond __Level of force to use in deleting the use.
4.5.3. NetUseEnum
WNetEnumResource should be used in place of NetUseEnum.
NetUseEnum lists all current connections between the local computer and resources on remote servers.
Privilege Level
This API cannot be executed on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetUseEnum (
IN LPWSTR reserved OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
reserved __Must be NULL.
level __Level of information provided. Must be 0, 1 or 2.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and 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, then no resume handle is stored..
4.5.4. NetUseGetInfo
WNetGetConnection should be used in place of NetUseGetInfo.
NetUseGetInfo retrieves information about a connection to a shared resource.
NET_API_STATUS NET_API_FUNCTION
NetUseGetInfo (
IN LPWSTR reserved OPTIONAL,
IN LPWSTR usename,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
reserved __Must be NULL.
usename __A pointer to an UNICODE string containing the local or remote name active use to return information on.
level __Level of information required. 0, 1 and 2 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.6. Share APIs
Share API 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.
NetShareAdd allows a user or application to share a resource of a specific type using the specified sharename. NetShareAdd requires the sharename and local devicename to share the resource. A user or application must have an account on the server to access the resource.
LAN Manager defines three types of special sharenames for interprocess communication (IPC) and remote administration of the server:
o IPC$, reserved for interprocess communication.
o ADMIN$, reserved for remote administration.
o A$, B$, C$ (and other local disk names followed by a dollar sign), assigned to local disk devices.
Share APIs are available at three information levels.
typedef struct _SHARE_INFO_0 {
LPWSTR shi0_netname;
} SHARE_INFO_0, *PSHARE_INFO_0, *LPSHARE_INFO_0;
typedef struct _SHARE_INFO_1 {
LPWSTR shi1_netname;
DWORD shi1_type;
LPWSTR shi1_remark;
} SHARE_INFO_1, *PSHARE_INFO_1, *LPSHARE_INFO_1;
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;
The following infolevels are only valid for NetShareSetInfo and replace the older way of passing in a Parmnum to set a specific field.
The following are supported on downlevel systems (i.e. LANMan 2.x) as well:
For NetShareSetInfo, parmnum values refer to the fields in the share_info structure as follows. These values are used when indicating an error in a specific parameter via parm_err.
parmnum value Field in share_info struct
SHI_NETNAME_PARMNUM shi_netname
SHI_TYPE_PARMNUM shi_type
SHI_REMARK_PRAMNUM shi_remark
SHI_PERMISSIONS_PARMNUM shi_permissions
SHI_MAX_USES_PARMNUM shi_max_uses
SHI_CURRENT_USES_PARMNUM shi_current_uses
SHI_PATH_PARMNUM shi_path
SHI_PASSWD_PARMNUM shi_passwd
The Share APIs are:
4.6.1. NetShareAdd
NetShareAdd shares a server resource.
Privilege Level
Do we still have comm operator and comm device queues?
This is now sticky, correct?
Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareAdd on a remote server or on a computer that has local security enabled. The print operator can add only printer queues. The comm operator can add only communication-device queues.
NET_API_STATUS NET_API_FUNCTION
NetShareAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information provided. Must be 2.
buf __A pointer to a buffer containing the share information structure.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.6.2. NetShareEnum
WNetEnumResource should be used in place of NetShareEnum.
NetShareEnum retrieves information about each shared resource on a server.
Privilege Level
Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareEnum at level 2 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 or level 1 calls.
NET_API_STATUS NET_API_FUNCTION
NetShareEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 0, 1 and 2 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing share 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..
4.6.3. NetShareGetInfo
NetShareGetInfo retrieves information about a particular shared resource on a server.
Privilege Level
Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareGetInfo at level 2 on a remote server or on a computer that has local security enabled. No special privilege is required for level 0 or level 1 calls.
NET_API_STATUS NET_API_FUNCTION
NetShareGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR netname,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
netname __A pointer to an UNICODE string containing the netname of the share to return information on.
level __Level of information required. 0, 1 and 2 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.6.4. NetShareSetInfo
NetShareSetInfo sets the parameters of a shared resource.
Is this SetInfo also sticky?
Privilege Level
Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareSetInfo on a remote server or on a computer that has local security enabled. The print operator can set information only about printer queues. The comm operator can set information only about communication-device queues.
NET_API_STATUS NET_API_FUNCTION
NetShareSetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR netname,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
netname __A pointer to an UNICODE string containing the netname of the share to set information on.
level __Level of information to set. 1, 2, 1004 - 1006 and 1009 are valid.
buf __A pointer to a buffer containing the share information.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.6.5. NetShareDel
NetShareDel deletes a sharename from a server's list of shared resources, disconnecting all connections to the shared resource.
Privilege Level
Admin privilege or comm, print, or server operator privilege is required to successfully execute NetShareDel on a remote server or on a computer that has local security enabled. The print operator can delete only printer queues. The comm operator can delete only communication-device queues.
NET_API_STATUS NET_API_FUNCTION
NetShareDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR netname,
IN DWORD reserved
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
netname __A pointer to an UNICODE string containing the netname of the share to delete.
reserved __Reserved, must be zero.
4.6.6. NetShareCheck
NetShareCheck checks whether or not a server is sharing a device.
Privilege Level
No special privilege level is required to successfully execute NetShareCheck.
NET_API_STATUS NET_API_FUNCTION
NetShareCheck (
IN LPWSTR servername OPTIONAL,
IN LPWSTR device,
OUT LPDWORD type
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
device __A pointer to an UNICODE string containing the name of the device to check for shared access.
type __On return the address pointed to by the type parameter contains the type of share the device is offered with. This field is only set if success was returned.
4.7. Session
Session API functions control network sessions established between workstations and servers. They require that the Server service be started on the specified server. A session is a link between a workstation and a server. It is established the first time a workstation makes a connection with a shared resource on the server. Until the session ends, all further connections between the workstation and the server are part of this same session. To end a session, an application on the server end of a connection calls NetSessionDel. This deletes all current connections between the workstation and the server. NetSessionEnum returns information about all sessions established for a server. NetSessionGetInfo returns information about a particular session.
Per-user information is managed by the NetSession APIs via the use of the username parameter. Since there can be multiple users per session, this parameter is necessary in order to access the user-specific information for the session.
Session APIs are available at four information levels.
sesi_username cannot be NULL. sesi1_flags and sesi2_flags can take the following bits:
SESS_GUEST 0x00000001
SESS_NONENCRYPTION 0x00000002
The session APIs are:
4.7.1. NetSessionEnum
NetSessionEnum provides information about all current sessions.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetSessionEnum at level 1 or level 2. No special privilege is required for level 0 or level 10 calls.
NET_API_STATUS NET_API_FUNCTION
NetSessionEnum (
IN LPWSTR servername OPTIONAL,
IN LPWSTR clientname OPTIONAL,
IN LPWSTR username OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
clientname __A pointer to an UNICODE string containing the name of the computer session for which information is to be returned. A NULL pointer or string specifies that all computer sessions on the server are to be ennumerated.
username __A pointer to an UNICODE string containing the name of the the user for which to ennumerate the sessions. A NULL pointer or string specifies that sessions for all users are to be ennumerated.
level __Level of information required. 0, 1, 2 and 10 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing session 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.
4.7.2. NetSessionGetInfo
NetSessionGetInfo retrieves information about a session established between a particular server and workstation.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetSessionGetInfo at level 1 or level 2. No special privilege is required for level 0 or level 10 calls.
NET_API_STATUS NET_API_FUNCTION
NetSessionGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR clientname,
IN LPWSTR username,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
clientname __A pointer to an UNICODE string containing the name of the computer session for which information is to be returned. This field cannot be NULL.
username __A pointer to an UNICODE string containing the name of the user whose session information is to be returned. This field cannot be NULL.
level __Level of information required. 0, 1, 2 and 10 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.7.3. NetSessionDel
NetSessionDel ends a session between a server and a workstation.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetSessionDel.
NET_API_STATUS NET_API_FUNCTION
NetSessionDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR clientname,
IN LPWSTR username,
IN DWORD reserved
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
clientname __A pointer to an UNICODE string containing the computer name of the client to disconnect. If clientname is NULL, then all the sessions of the user in username will be deleted on the server specified.
username __A pointer to an UNICODE string containing the name of the user whose session is to be terminated. A NULL indicates that all users' sessions from the clientname specified are to be terminated.
reserved __reserved, must be zero.
4.8. Connection APIs
WNetConnection APIs should be used in place of NetConnection APIs.
The Connection API function, NetConnectionEnum, lists server connections. A computer accesses a shared resource on a server by means of a connection. A connection is a software link between a computer and a server, made by assigning a local or NULL devicename to the shared resource on the server. The NetUseAdd function establishes connections.
NetConnectionEnum lists information about all connections to a server made by a specified computer, or about all connections made to a specified sharename.
Connection APIs are available at two information levels:
WNetEnumResource should be used in place of NetConnectionEnum.
NetConnectionEnum 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 different username.
Privilege Level
Admin privilege or server, print, or comm operator privilege is required to successfully execute NetConnectionEnum.
NET_API_STATUS NET_API_FUNCTION
NetConnectionEnum (
IN LPWSTR servername OPTIONAL,
IN LPWSTR qualifier,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
qualifier __A pointer to an UNICODE string containing a sharename or computername for the connections of interest. If it is a sharename, then all the connections made to that sharename are listed. If it is a computername (i.e. it starts with two backslash characters), then NetConnectionEnum lists all connections made from that computer to the server specified.
level __Level of information required. 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing connection 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..
4.9. File APIs
File API functions provide a way to monitor and close the file, device, and pipe resources open on a server. NetFileClose forces a server resource closed. This function can be used when a system error prevents normal closure. NetFileEnum 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. NetFileEnum returns an entry for each file opening. NetFileGetInfo returns information about one particular opening of a resource.
File APIs are available at information levels 2 and 3 only. Levels 0 and 1 are not supported.
typedef struct _FILE_INFO_2 {
DWORD fi2_id;
} FILE_INFO_2, *PFILE_INFO_2, *LPFILE_INFO_2;
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;
The file APIs are:
4.9.1. NetFileEnum
NetFileEnum supplies information about some or all open files on a server, allowing the user to supply a resume handle and get required information through repeated calls to the function.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetFileEnum.
NET_API_STATUS NET_API_FUNCTION
NetFileEnum (
IN LPWSTR servername OPTIONAL,
IN LPWSTR basepath,
IN LPWSTR username,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
basepath __A pointer to an UNICODE string containing a qualifier for the returned information. If NULL then all open resources are enumerated, else only resources which have basepath as a prefix are enumerated. A prefix is the path component up to a back-slash.
username __A pointer to an UNICODE string that specifies the name of the user. If not NULL, username serves as a qualifier to the ennumeration. The files returned are limited to those that have usernames matching the qualifier. If username is NULL, no username qualifier is used.
level __Level of information required. 2 and 3 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing file 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..
4.9.2. NetFileGetInfo
NetFileGetInfo retrieves information about a particular opening of a server resource.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetFileGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetFileGetInfo (
IN LPWSTR servername OPTIONAL,
IN DWORD fileid,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
fileid __The fileid of the open resource to return information on. The fileid value must be that returned in a previous enumeration call.
level __Level of information required. 2 and 3 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.9.3. NetFileClose
NetFileClose forces a resource to close. This function can be used when an error prevents closure by other means.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetFileClose.
NET_API_STATUS NET_API_FUNCTION
NetFileClose (
IN LPWSTR servername OPTIONAL,
IN DWORD fileid
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
fileid __The fileid of the opened resource instance to be closed.
4.10. Message APIs
Message API functions send and receive messages and manipulate message aliases. 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 using NetMessageNameAdd. 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. NetMessageNameDel deletes a specific message alias from the message name table. NetMessageNameEnum lists all the aliases stored in the message name table. NetMessageNameGetInfo retrieves information about a particular message alias in the message name table.
To send a message, an application calls NetMessageBufferSend.
Applications can also send broadcast messages to all users in a domain or to all computers on a network using NetMessageBufferSend.
Message APIs are available at two information levels.
MSG_INFO_1 only exists for compatability. The NT messenger will not forward names or allow names to be forwarded to it.
typedef struct _MSG_INFO_0 {
LPWSTR msgi0_name;
} MSG_INFO_0, *PMSG_INFO_0, *LPMSG_INFO_0;
typedef struct _MSG_INFO_1 {
LPWSTR msgi1_name;
DWORD msgi1_forward_flag;
LPWSTR msgi1_forward;
} MSG_INFO_1, *PMSG_INFO_1, *LPMSG_INFO_1;
The Message APIs are:
4.10.1. NetMessageNameAdd
NetMessageNameAdd registers a message alias in the message name table. NetMessageNameAdd requires that the Messenger service be started.
Privilege Level
Admin privilege is required to successfully execute NetMessageNameAdd on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetMessageNameAdd (
IN LPWSTR servername OPTIONAL,
IN LPWSTR msgname
};
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
msgname __A pointer to an UNICODE string of limit 15 characters containing the message name to be added.
Note. The forward action flag from the LANMan 2.x NetMessageNameAdd is no longer a parameter as message forwarding is no longer supported. If the NetMessageNameAdd API detects that a forwarded version of msgname exists on the network then the API will fail with error NERR_Already_Exists.
4.10.2. NetMessageNameEnum
NetMessageNameEnum lists the message aliases that will receive messages on a specified computer. NetMessageNameEnum requires that the Messenger service be started.
Privilege Level
Admin privilege is required to successfully execute NetMessageNameEnum on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetMessageNameEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing message name 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..
4.10.3. NetMessageNameGetInfo
NetMessageNameGetInfo retrieves information about a particular message alias in the message name table. NetMessageNameGetInfo requires that the Messenger service be started.
Privilege Level
Admin privilege is required to successfully execute NetMessageNameGetInfo on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetMessageNameGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR msgname,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
msgname __A pointer to an UNICODE string containing the message name to return information on.
level __Level of information required. 0 & 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.10.4. NetMessageNameDel
NetMessageNameDel deletes a message alias from the table of message aliases on a computer. NetMessageNameDel requires that the Messenger service be started.
Privilege Level
Admin privilege is required to successfully execute NetMessageNameDel on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetMessageNameDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR msgname
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
msgname __A pointer to an UNICODE string of limit 15 characters containing the message name to be deleted.
4.10.5. NetMessageBufferSend
NetMessageBufferSend sends a buffer of information to a registered message alias.
Privilege Level
No special privilege is required to execute NetMessage buffer send locally. Admin, accounts, print, or server operator privilege is required to successfully execute NetMessageBufferSend on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetMessageBufferSend (
IN LPWSTR servername OPTIONAL,
IN LPWSTR msgname,
IN LPWSTR fromname,
IN LPBYTE buf,
IN DWORD buflen
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
msgname __A pointer to an UNICODE string containing the message name to which the message buffer should be sent.
fromname __A pointer to an UNICODE string containing the message name sending the information. fromname is a new parameter for Windows networking. This parameter is needed for sending alerts from the computer name rather than the logged on user. If a NULL is specified the message is send from the logged on user as with LANMan 2.x.
buf __A pointer to a buffer of message text.
buflen __The length in bytes of the message text in buf.
4.11. Remote Utility API
Remote Utility API functions enable applications to access the time-of-day information on a remote server.
NetRemoteTOD returns time-of-day information from a remote server.
4.11.1. NetRemoteTOD API
The remote time of day information is available at one information level:
No special privilege level is required to successfully execute NetRemoteTOD.
NET_API_STATUS NET_API_FUNCTION
NetRemoteTOD (
IN LPWSTR servername OPTIONAL,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
4.12. Security Account APIs
4.12.1. User APIs
User API functions control a user's account in the security database. Each user or application that accesses resources must have an account in the security database. The NT Security system (SAM) uses this user account to verify that the user or application has permission to use 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.
NetUserEnum can be used to list all user accounts in a domain. An application can change a user's privilege level by calling NetUserSetInfo. It can also change the user's resource access privileges by modifying that user's groups (for more information, see the Group category API functions). Individually assigned user privileges take precedence over group privileges. An application can verify the groups to which a user belongs by calling NetUserGetGroups, which returns a list of global groupnames. The NetUserGetLocalGroups function does the same for local groups. When a user account is no longer needed, use NetUserDel to delete the account from the server. Once the account is removed, the user can no longer access the server, except by using the guest account. Because the user's password is confidential, it is not returned by NetUserEnum or NetUserGetInfo. The password is initially assigned when NetUserAdd is called. NetUserSetInfo sets the password and other elements of a user account.
User account information is available at five levels:
typedef struct _USER_INFO_0 {
LPWSTR usri0_name;
} USER_INFO_0, *PUSER_INFO_0, *LPUSER_INFO_0;
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;
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;
LPBYTE 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;
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;
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;
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;
LPBYTE usri11_logon_hours;
DWORD usri11_code_page;
} USER_INFO_11, *PUSER_INFO_11, *LPUSER_INFO_11;
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;
The following infolevels are only valid for NetUserSetInfo and replace the older way of passing in a Parmnum to set a specific field.
The following are supported on downlevel systems (i.e. LANMan 2.x) as well:
For NetUserSetInfo, parmnum values refer to the fields in the user_info structure as follows. These values are used when indicating an error in a specific parameter via parm_err.
Admin privilege or account operator privilege is required to successfully execute NetUserAdd.
NET_API_STATUS NET_API_FUNCTION
NetUserAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information provided. Must be 1, 2 or 3.
buf __A pointer to a buffer containing the user information structure.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.1.2. NetUserEnum
NetUserEnum provides resumable enumeration of information about each user account in a domain.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserEnum at levels 1 and 2. No special privilege is required at level 0 or 10.
NET_API_STATUS NET_API_FUNCTION
NetUserEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN DWORD filter,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 0, 1, 2, 3, 10, 11 and 20 are valid.
filter__Specifies a filter of account types ot enumerate. 0 implies all account types. Allowable values are:
FILTER_TEMP_DUPLICATE_ACCOUNTS
FILTER_NORMAL_ACCOUNT
FILTER_INTERDOMAIN_TRUST_ACCOUNT
FILTER_WORKSTATION_TRUST_ACCOUNT
FILTER_SERVER_TRUST_ACCOUNT
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing user 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..
4.12.1.3. NetUserGetInfo
NetUserGetInfo retrieves information about a particular user account on a server.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserGetInfo at level 1 and 2. No special privilege is required at levels 0 or 10. A user may call NetUserGetInfo on his/her own account at level 11.
NET_API_STATUS NET_API_FUNCTION
NetUserGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR username,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
username __A pointer to an UNICODE string containing the name of the user account on which to return information.
level __Level of information required. 0, 1, 2, 3,10,11 and 20 are valid.
bufptr __A pointer to the return information structure is returned in the address pointed to by bufptr.
4.12.1.4. NetUserSetInfo
NetUserSetInfo sets the parameters of a user account.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserSetInfo. A user may call NetUserSetInfo to set certain information on his/her own account.
NET_API_STATUS NET_API_FUNCTION
NetUserSetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR username,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
username __A pointer to an UNICODE string containing the name of the user account to set information on.
level __Level of information to set. 0, 1, 2, 3, or 20.
buf __A pointer to a buffer containing the user information.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.1.5. NetUserDel
NetUserDel deletes a user account from the accounts database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserDel.
NET_API_STATUS NET_API_FUNCTION
NetUserDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR username
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
username __A pointer to an UNICODE string containing the name of the user account to delete
4.12.1.6. NetUserGetGroups
NetUserGetGroups retrieves a list of global groups to which a specified user belongs.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserGetGroups.
NET_API_STATUS NET_API_FUNCTION
NetUserGetGroups (
IN LPWSTR servername OPTIONAL,
IN LPWSTR username,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
username __A pointer to an UNICODE string containing the name of the user to return global group membership for.
level __Level of information required. Only 0 or 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr. The returned information is an array of GROUP_USERS_INFO_x structures..
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
4.12.1.7. NetUserGetLocalGroups
NetUserGetLocalGroups retrieves a list of local groups to which a specified user belongs.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserGetLocalGroups.
NET_API_STATUS NET_API_FUNCTION
NetUserGetLocalGroups (
IN LPWSTR servername OPTIONAL,
IN LPWSTR username,
IN DWORD level,
IN DWORD flags,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
username __A pointer to an UNICODE string containing the name of the user to return global group membership for.
level __Level of information required. Only 0 is valid.
flags __Bitmask of flags. Currently, only LG_INCLUDE_INDIRECT is defined. If this bit is set, the function will also return localgroups the user is a member of indirectly (ie. by the virtue of being in a globalgroup that itself is a member of one or more localgroups).
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr. The returned information is an array of LOCALGROUP_USERS_INFO_0 structures..
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
4.12.1.8. NetUserSetGroups
NetUserSetGroups sets global group memberships for a specified user account.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserSetGroups.
NET_API_STATUS NET_API_FUNCTION
NetUserSetGroups (
IN LPWSTR servername OPTIONAL,
IN LPWSTR username,
IN DWORD level,
IN LPBYTE bufptr,
IN DWORD num_entries
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
username __A pointer to an UNICODE string containing the name of the user to set global group memberships for.
level __Level of information required. Only 0 or 1 are valid.
bufptr __A pointer to an array of global groups information structures.
num_entries__Number of global group information structures contained in the array pointed to by bufptr.
4.12.2. User Modal APIS
The user modal API functions control the system wide parameters which affect the NT Security system behaviour.
User modal information is available at three levels
The following infolevels are only valid for NetUserModalsSet and replace the older way of passing in a Parmnum to set a specific field.
The following are supported on downlevel systems (i.e. LANMan 2.x) as well. NOTE that the mapping from the old parmnum to the infolevel does not apply to the role and primary fields.
For NetUserModalsSet, parmnum values refer to the fields in the modals_info structure as follows. These values are used when indicating an error in a specific parameter via parm_err.
NetUserModalsGet retrieves global information for all users and global groups in the user account database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserModalsGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetUserModalsGet (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level__Level of information required. 0 1, and 2 are valid.
bufptr __A pointer to the return information structure is returned in the address pointed to by bufptr.
4.12.2.2. NetUserModalsSet
NetUserModalsSet sets global information for all users and global groups in the user account database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetUserModalsSet.
NET_API_STATUS NET_API_FUNCTION
NetUserModalsSet (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
username __A pointer to an UNICODE string containing the name of the user account to set information on.
level __Level of information to set. 0, 1 and 2 are valid.
buf __A pointer to a buffer containing the user modals information.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.3. Global Group APIs
The global group API functions control global groups of users in a way that can be used across domains. A global group is a set of users who share common permissions in the security database. Group API functions create or delete global groups, and review or adjust the membership of the global groups. The global group has a groupname that specifies the usernames of global group members.
To create a global group, an application calls NetGroupAdd, supplying a groupname. Initially, the global group has no members. To assign members to the global group, call NetGroupSetUsers. To add a user to an existing global group, call NetGroupAddUser. To set general information about the global group, call NetGroupSetInfo.
NetGroupDelUser deletes a specified username from a global group, and NetGroupDel disbands a global group. NetGroupDel works whether or not the global group has any members.
Three Group category API functions retrieve information about the global groups on a server: NetGroupEnum produces a list of all global groups; NetGroupGetUsers lists all members of a specified global group; and NetGroupGetInfo returns general information about the global group.
Each user account automatically belongs to one of the special global groups Domain Users or None, according to the user's privilege level. Membership of these global groups is indirectly controlled by the NetUserAdd, NetUserDel, and NetUserSetInfo functions. For more information, see the User category API functions.
Group API functions control groups of users.
Group account information is available at two levels:
typedef struct _GROUP_INFO_0 {
LPWSTR grpi0_name;
} GROUP_INFO_0, *PGROUP_INFO_0, *LPGROUP_INFO_0;
typedef struct _GROUP_INFO_1 {
LPWSTR grpi1_name;
LPWSTR grpi1_comment;
} GROUP_INFO_1, *PGROUP_INFO_1, *LPGROUP_INFO_1;
typedef struct _GROUP_INFO_2 {
LPWSTR grpi2_name;
LPWSTR grpi2_comment;
DWORD grpi2_group_id;
DWORD grpi2_attributes;
}GROUP_INFO_2, *PGROUP_INFO_2;
The Groups to which a user belongs may be obtained at one information level.
For NetGroupSetInfo, parmnum values refer to the fields in the group_info structure as follows. These values are used when indicating an error in a specific parameter via parm_err.
parmnum value Field in group_info struct
GROUP_NAME_PARMNUM grpi_name
GROUP_COMMENT_PARMNUM grpi_comment
GROUP_ATTRIBUTES_PARMNUM grpi_attributes
The Group APIs are:
4.12.3.1. NetGroupAdd
NetGroupAdd creates a global group in the security database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupAdd.
NET_API_STATUS NET_API_FUNCTION
NetGroupAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information provided. Must be 0 1, or 2.
buf __A pointer to a buffer containing the global group information structure.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.3.2. NetGroupAddUser
NetGroupAddUser gives an existing user account membership in an existing global group.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupAddUser.
NET_API_STATUS NET_API_FUNCTION
NetGroupAddUser (
IN LPWSTR servername OPTIONAL,
IN LPWSTR GroupName,
IN LPWSTR username
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
GroupName __A pointer to an UNICODE string containing the name of the global group to which the user is to be given membership.
Username __A pointer to an UNICODE string containing the name of the user to be given global group membership.
4.12.3.3. NetGroupEnum
NetGroupEnum retrieves information about each global group account.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupEnum.
NET_API_STATUS NET_API_FUNCTION
NetGroupEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing global group 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..
4.12.3.4. NetGroupGetInfo
NetGroupGetInfo retrieves information about a particular global group account on a server.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetGroupGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the global group account to return information on.
level __Level of information required. 0, 1 and 2 are valid.
bufptr __A pointer to the return information structure is returned in the address pointed to by bufptr.
4.12.3.5. NetGroupSetInfo
NetGroupSetInfo sets the parameters of a global group account.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupSetInfo.
NET_API_STATUS NET_API_FUNCTION
NetGroupSetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the global group account to set information on.
level __Level of information to set. Only 0, 1 and 2 are valid.
buf __A pointer to a buffer containing the global group information.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.3.6. NetGroupDel
NetGroupDel deletes a global group account from the accounts database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupDel.
NET_API_STATUS NET_API_FUNCTION
NetGroupDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the global group account to delete
4.12.3.7. NetGroupDelUser
NetGroupDelUser removes a user from a particular global group in the user account database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupDelUser.
NET_API_STATUS NET_API_FUNCTION
NetGroupDelUser (
IN LPWSTR servername OPTIONAL,
IN LPWSTR GroupName,
IN LPWSTR Username
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
GroupName __A pointer to an UNICODE string containing the name of the global group from which the user membership is to be removed.
Username __A pointer to an UNICODE string containing the name of the user to remove from the global group.
4.12.3.8. NetGroupGetUsers
NetGroupGetUsers retrieves a list of the members of a particular global group in the user account database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupGetUsers except when the request is made by a user who has membership in the specified global group in which case no special privilege is required.
NET_API_STATUS NET_API_FUNCTION
NetGroupGetUsers (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the global group whose members are to be listed.
level __Level of information required. Only 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing usergroup 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..
4.12.3.9. NetGroupSetUsers
NetGroupSetUsers sets the global group membership for the specified global group. Each user specified is made a member of the global group. Users that are not specified but are currently members of the global group will have their membership revoked.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetGroupSetUsers on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetGroupSetUsers (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN DWORD level,
IN LPBYTE buf,
IN DWORD totalentries
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the global group to which the specified users belong.
level __Level of information supplied. Only 0 is valid.
buf __Points to the buffer in which the data to be set is stored. This data consists of a sequence of _GROUP_USERS_INFO_0 data structures.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
4.12.4. Local Group APIs
A local group is a set of users who share common permissions in the security database. A local group can have members which are either users or global groups (global groups can only contain users). The local group API functions control members of local groups in a way that can only be used by the systems within a "cluster". A "cluster" is the individual workstation if the system is a Windows NT system, but it contains all the NT Advanced Servers of a domain if the system is a NT Advanced Server. Thus, a local group defined on a workstation can only be used on that workstation, but a local group defined on an Advanced Server can be used by any other Advanced Server within the same domain. The local group API functions create or delete local groups, and review or adjust the memberships of local groups.
A member can be added to a local group by specifying the security identifier (SID) of the member. The Win32 LookupAccountName API can be used to translate a member account name to a SID.
To create a local group, an application calls NetLocalGroupAdd, supplying a local group name. Initially, the local group has no members. To assign members to the local group, call NetLocalGroupSetMembers. To add a member to an existing local group, call NetLocalGroupAddMember. To set general information about the local group, call NetLocalGroupSetInfo.
NetLocalGroupDelMember deletes a specified member from a local group, and NetLocalGroupDel disbands a local group, deleting all existing members of the local group first.
Three local group category API functions retrieve information about the local groups on a server: NetLocalGroupEnum produces a list of all local groups; NetLocalGroupGetMembers lists all members of a specified local group; and NetLocalGroupGetInfo returns general information about the local group.
Group account information is available at three levels:
For NetLocalGroupSetInfo, parmnum values refer to the fields in the group_info structure as follows. These values are used when indicating an error in a specific parameter via parm_err.
parmnum value Field in group_info struct
LOCALGROUP_NAME_PARMNUM lgrpi_name
LOCALGROUP_COMMENT_PARMNUM lgrpi_comment
The Local Group APIs are:
4.12.4.1. NetLocalGroupAdd
NetLocalGroupAdd creates a local group in the security database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupAdd.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information provided. Must be 0 or 1.
buf __A pointer to a buffer containing the local group information structure.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.4.2. NetLocalGroupAddMember
NetLocalGroupAddMember gives an existing user account or global group membership in an existing local group.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupAddMember.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupAddMember (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN PSID membersid
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the local group to which the user or global group is to be given membership.
membersid __A pointer to the SID of a user or global group from the local, primary, or trust domains to be given local group membership.
4.12.4.3. NetLocalGroupEnum
NetLocalGroupEnum retrieves information about each local group account.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupEnum.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and 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 resumehandle is NULL, then no resume handle is stored..
4.12.4.4. NetLocalGroupGetInfo
NetLocalGroupGetInfo retrieves information about a particular local group account on a server.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the local group account to return information on.
level __Level of information required. 0 and 1 are valid.
bufptr __A pointer to the return information structure is returned in the address pointed to by bufptr.
4.12.4.5. NetLocalGroupSetInfo
NetLocalGroupSetInfo sets the parameters of a local group.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupSetInfo.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupSetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the local group account to set information on.
level __Level of information to set. 0, 1, and 1002 are valid.
buf __A pointer to a buffer containing the local group information.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.4.6. NetLocalGroupDel
NetLocalGroupDel deletes a local group account and all its members from the accounts database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupDel.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the local group account to delete
4.12.4.7. NetLocalGroupDelMember
NetLocalGroupDelMember removes a member from a particular local group in the security database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupDelMember.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupDelMember (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN PSID membersid
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the local group from which the user membership is to be removed.
membersid __A pointer to a SID of a user or global group to remove from the local group.
4.12.4.8. NetLocalGroupGetMembers
NetLocalGroupGetMembers retrieves a list of the members of a particular local group in the security database.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupGetMembers except when the request is made by a user who has membership in the specified local group in which case no special privilege is required.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupGetMembers (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the local group whose members are to be listed.
level __Level of information required. Levels 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing usergroup 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..
4.12.4.9. NetLocalGroupSetMembers
NetLocalGroupSetMembers sets the local group 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 are currently members of the local group will have their membership revoked.
Privilege Level
Admin privilege or account operator privilege is required to successfully execute NetLocalGroupSetMembers on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetLocalGroupSetMembers (
IN LPWSTR servername OPTIONAL,
IN LPWSTR groupname,
IN DWORD level,
IN LPBYTE buf,
IN DWORD totalentries
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
groupname __A pointer to an UNICODE string containing the name of the local group to which the specified users or global groups belong.
level __Level of information supplied. Only 0 is valid.
buf __Points to the buffer in which the data to be set is stored. This data consists of a sequence of LOCALGROUP_MEMBERS_INFO_0 data structures.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
4.12.5. Access APIs
A full set of Access setting APIs exist in Win32. These should be used in place of the NetAccess APIs. The NetAccess APIs only work when remoted to a downlevel system.
Access Permissions API functions examine or modify user or group access permissions for specified 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 username or groupname and its corresponding access permissions.
The audit attribute field defines what type of events will be audited for that resource. It is possible to audit various types of events, depending on whether the resource is a file or a directory. It is possible to audit events such as opening, writing, and deleting a file; creating or deleting a directory; and changing the ACL of the resource.
NetAccessAdd creates an ACL for a resource and sets username or groupname access permissions. NetAccessDel deletes the ACL for a resource. NetAccessGetInfo returns the ACL for a particular resource. NetAccessEnum returns information about all ACLs.
Only users or applications with admin privilege or special permission for the resource can define or examine access permissions on a remote server or on a computer that has local security. Users have special permissions for a resource when they are granted ACCESS_PERM permission for that resource; this is also known as P permission.
NetAccessCheck verifies whether a user has permission to perform a specified operation on a particular resource. If access permission is needed, you can use NetAccessSetInfo to change the ACL. NetAccessGetUserPerms returns a specified user's or group's permission for a specified resource.
Access Permission information is available at two levels:
For NetAccessSetInfo, parmnum values refer to the fields in the access_info structure as follows. These values are used when indicating an error in a specific parameter via parm_err.
parmnum value Field in access_info struct
ACCESS_RESOURCE_NAME_PARMNUM acc_resource_name
ACCESS_ATTR_PARMNUM acc_attr
ACCESS_COUNT_PARMNUM acc_count
ACCESS_ACCESS_LIST_PARMNUM array following acc1_count
The following are defined for the bits in the acc1_attr field of _ACCESS_INFO_1:
ACCESS_AUDIT 0x001
ACCESS_SUCCESS_OPEN 0x010
ACCESS_SUCCESS_WRITE 0x020
ACCESS_SUCCESS_DELETE 0x040
ACCESS_SUCCESS_ACL 0x080
ACCESS_SUCCESS_MASK 0x0F0
ACCESS_FAIL_OPEN 0x100
ACCESS_FAIL_WRITE 0x200
ACCESS_FAIL_DELETE 0x400
ACCESS_FAIL_ACL 0x800
ACCESS_FAIL_MASK 0xF00
ACCESS_FAIL_SHIFT 0x004
The Access Permission APIs are:
4.12.5.1. NetAccessAdd
Only works when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) APIs for NT.
NetAccessAdd creates a new Access Control List (ACL) for a resource.
Privilege Level
Admin privilege is required to successfully execute NetAccessAdd.
NET_API_STATUS NET_API_FUNCTION
NetAccessAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information provided. Must be 1.
buf __A pointer to a buffer containing the access information structure.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.5.2. NetAccessEnum
Only works when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) APIs for NT.
NetAccessEnum retrieves information about each access permision record.
NetAccessEnum is being phased out and is only available at levels 0 and 1 for Windows networking. It is recommended that NetAccessEnum not be used because it is unlikely to be supported in future releases.
Privilege Level
NetAccessEnum does not require admin privilege to execute but will only return records for entries for which the user has 'P' permission if the caller does not have admin privilege.
NET_API_STATUS NET_API_FUNCTION
NetAccessEnum (
IN LPWSTR servername OPTIONAL,
IN LPWSTR basepath,
IN DWORD recursive,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
basepath __A pointer to an UNICODE string that contains a base pathname for the resources. 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.
recursive __A flag to enables or disable recursive searching. If recursive is 0, NetAccessEnum returns entries only for the resource named as the base path by basepath and for the resources directly below that base path. If recursive is nonzero, NetAccessEnum returns entries for all access control lists (ACLs) that have basepath at the beginning of the resource name.
level __Level of information required. Only 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and is used to continue an existing access 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..
4.12.5.3. NetAccessGetInfo
Only works when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) APIs for NT.
NetAccessGetInfo retrieves the access control information for a specific resource.
Privilege Level
Admin privilege or P permission is required to successfully execute NetAccessGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetAccessGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR resource,
IN DWORD level,
OUT LPBYTE * bufptr,
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
resource __A pointer to an UNICODE string containing the name of the resource on which to return access control information.
level __Level of information required. 0 and 1 are valid.
bufptr __A pointer to the return information structure is returned in the address pointed to by bufptr.
4.12.5.4. NetAccessSetInfo
Only works when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) APIs for NT.
NetAccessSetInfo changes the access control list for a resource.
Privilege Level
Admin privilege or P permission for the resource is required to successfully execute NetAccessSetInfo.
NET_API_STATUS NET_API_FUNCTION
NetAccessSetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR resource,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
resource __A pointer to an UNICODE string containing the name of the resource for which the access information shoule be changed.
level __Level of information to set. Only 1 and 1002 are valid.
buf __A pointer to a buffer containing the access entry information.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.12.5.5. NetAccessDel
Only works when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) APIs for NT.
NetAccessDel deletes the access control list for a particular resource.
Privilege Level
Admin privilege or P permission for the resource is required to successfully execute NetAccessDel.
NET_API_STATUS NET_API_FUNCTION
NetAccessDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR resource
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
resource __A pointer to an UNICODE string containing the name of the resource for which to remove the access control entry.
4.12.5.6. NetAccessGetUserPerms
Only works when remoted to a downlevel system. Use Win32 (GetFileSecurity, SetFileSecurity) APIs for NT.
NetAccessGetUserPerms returns a specified user's or group's access permissions for a particular resource..
Privilege Level
Admin privilege or P permission for the resource is required to successfully execute NetAccessGetUserPerms.except when users request their own access permissions to a resource. In this case no special privilege is required.
NET_API_STATUS NET_API_FUNCTION
NetAccessGetUserPerms (
IN LPWSTR servername OPTIONAL,
IN LPWSTR UGname,
IN LPWSTR resource,
OUT LPDWORD Perms
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
UGname __A pointer to an UNICODE string containing the name of the user or group to query permissions for.
resource __A pointer to an UNICODE string containing the resource for which to query user permissions.
Perms __Points to a DWORD in which the user permissions for the specified resource are returned.
4.12.5.7. NetAccessCheck
Only works when remoted to a downlevel system. Use Win32 (AccessCheck) API for NT.
NetAccessCheck verifies that a user has permission to perform a specified operation on a particular resource.
Privilege Level
Admin privilege is required to successfully execute NetAccessCheck.
NET_API_STATUS NET_API_FUNCTION
NetAccessCheck (
IN LPWSTR servername OPTIONAL,
IN LPWSTR username,
IN LPWSTR resource,
IN DWORD operation,
OUT LPDWORD result
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
username __A pointer to an UNICODE string containing the name of the user to check for access to the resource.
resource __A pointer to an UNICODE string containing the resource for which to check user permissions.
operation __Points to a DWORD specifying the type of access operation requested.
ACCESS_READ 0x01 Permission to read data from a resource
and, by default, execute the resource.
ACCESS_WRITE 0x02 Permission to write data to the
resource.
ACCESS_CREATE 0x04 Permission to create an instance of the
resource (for example, a file); data
can be written to the resource when
creating it.
ACCESS_EXEC 0x08 Permission to execute the resource.
ACCESS_DELETE 0x10 Permission to delete the resource.
ACCESS_ATRIB 0x20 Permission to modify the resource's
attributes (for example, the date and
time a file was last modified).
ACCESS_PERM 0x40 Permission to modify the permissions
(read, write, create, execute, and
delete) assigned to a resource for a
user, group, or application.
ACCESS_ALL 0x7F Permission to read, write, create,
execute, or delete a resource, or to
modify attributes or permissions.in
which the user permissions for the
specified resource are returned.
result __Points to a DWORD in which the result of the access check is returned.
4.13. Domain APIs
Domain API functions retrieve information about a domain. They require that the workstation service be started.
The Domain APIs are:
4.13.1. NetGetDCName
NetGetDCName returns the name of the Primary Domain Controller for the specified domain.
Privilege Level
No special privilege is required to successfully execute NetGetDCName.
NET_API_STATUS NET_API_FUNCTION
NetGetDCName (
IN LPWSTR servername OPTIONAL,
IN LPWSTR domainname,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
domainname __A pointer to an UNICODE string containing the name of the domain. A NULL pointer or string indicates that the name of the domain controller for the primary domain is to be returned.
bufptr __A pointer to the buffer containing the domain controller name is returned in the address pointed to by bufptr.
4.14. Transport APIs
Transport APIs handle binding and unbinding of transports to/from the server and redirector, and also ennumerate the transports used by a component. The ServerTransport APIs deal with transports managed by the server, and the WkstaTransport APIs deal with transports managed by the redirector.
NetServerTransportAdd allows the user to bind the transport to the server. NetServerTransportDel allows the user to unbind the server from the transport. NetServerTransportEnum ennumerates the transports that are managed by the server.
NetWkstaTransportAdd/Del/Enum perform equivalent operations for the workstation.
ServerTransport APIs are available at one information level.
NetServerTransportAdd binds the server to the transport.
Privilege Level
Admin privilege is required to successfully execute NetServerTransportAdd.
NET_API_STATUS NET_API_FUNCTION
NetServerTransportAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. Only 0 is valid.
buf __A pointer to a buffer containing the server transport information structure.
4.14.2. NetServerTransportDel
NetServerTransportDel unbinds the transport from the server.
Privilege Level
Admin privilege is required to successfully execute NetServerTransportDel.
NET_API_STATUS NET_API_FUNCTION
NetServerTransportDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR transportname
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
transportname __A pointer to an UNICODE string containing the name of the transport from which to unbind.
4.14.3. NetServerTransportEnum
NetServerTransportEnum supplies information about transports that are managed by the server.
Privilege Level
No special privilege is required to successfully execute NetServerTransportEnum.
NET_API_STATUS NET_API_FUNCTION
NetServerTransportEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. Only 0 is valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and 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, then no resume handle is stored..
4.14.4. NetWkstaTransportAdd
NetWkstaTransportAdd binds the redirector to the transport.
Privilege Level
Admin privilege is required to successfully execute NetWkstaTransportAdd.
NET_API_STATUS NET_API_FUNCTION
NetWkstaTransportAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. Only 0 is valid.
buf __A pointer to a buffer containing the server transport information structure.
4.14.5. NetWkstaTransportDel
NetWkstaTransportDel unbinds the transport from the redirector.
Privilege Level
Admin privilege is required to successfully execute NetWkstaTransportDel.
NET_API_STATUS NET_API_FUNCTION
NetWkstaTransportDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR transportname,
IN DWORD ucond
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
transportname __A pointer to an UNICODE string containing the name of the transport from which to unbind.
ucond __Force level to delete connections on the transport binding.
4.14.6. NetWkstaTransportEnum
NetWkstaTransportEnum supplies information about transports that are managed by the redirector.
Privilege Level
No special privilege is required to successfully execute NetWkstaTransportEnum.
NET_API_STATUS NET_API_FUNCTION
NetWkstaTransportEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to an UNICODE string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. Only 0 is valid.
bufptr __On return a pointer to the return information structure is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
entriesread __On return the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and 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, then no resume handle is stored..
4.15. Alert APIs
Alert API functions notify network service programs and applications of network events. An event is a particular instance of a process or state of hardware as defined by an application. The Alert API functions allow applications to indicate when predefined events occur.
NetAlertRaise is used to indicate that an event has occurred.
The fixed-length header contains the standard alert data structure. The STD_ALERT data structure has the following format:
typedef struct _STD_ALERT {
DWORD alrt_timestamp;
WCHAR alrt_eventname[EVLEN+1];
WCHAR alrt_servicename[SNLEN+1];
} STD_ALERT, *PSTD_ALERT, *LPSTD_ALERT;
The ADMIN_OTHER_INFO data structure has this format:
* Followed by a number of consecutive UNICODE strings;
* the count is in the alrtus_numstrings element. */
*/
WCHAR mergestrings[];
/* Further followed by two more consecutive UNICODE strings. */
WCHAR username[];
WCHAR computername[];
The APIs are:
4.15.1. NetAlertRaise
NetAlertRaise notifies all registered clients that a particular event occurred.
Privilege Level
No special privilege level is required to successfully execute NetAlertRaise.
NET_API_STATUS NET_API_FUNCTION
NetAlertRaise (
IN LPWSTR event,
IN LPBYTE buffer,
IN DWORD numbytes
);
Parameters:
event __Points to an UNICODE string that specifies which type of alert to raise.
buffer __Points to the data to be sent to the clients listening for this alert. The data should consist of the STD_ALERT data structure followed by any additional alert data.
numbytes __Specifies the size of the buffer in bytes.
4.15.2. NetAlertRaiseEx
NetAlertRaiseEx simplifies the raising of an admin alert.
Privilege Level
No special privilege level is required to successfully execute NetAlertRaiseEx.
NET_API_STATUS NET_API_FUNCTION
NetAlertRaiseEx (
IN LPWSTR event,
IN LPVOID VariableInfo,
IN DWORD VariableInfoSize,
IN LPWSTR ServiceName
);
Parameters:
event __Points to an UNICODE string that specifies which type of alert to raise.
VariableInfo __Information to put into the admin alert.
VariableInfoSize __Number of bytes of variable information.
ServiceName __Name of the service raising the admin alert.
4.16. Error Logging APIs
Only use these for remoting to downlevel. For NT use the EventLog API (ReadEventlog, ReportEvent, ...)
Windows NT uses an integrated Eventlogging mechanism for reporting both errors and audits. The NetError and NetAudit APIs are provided to access downlevel LANMan logs. They will report ERROR_NOT_SUPPORTED if called to an Windows NT system.
The error log is a file that stores error messages (in binary format). It contains information about LAN Manager software internal errors, MS OS/2 and MS-DOS internal errors, and network service errors.
NetErrorLogRead reads entries from the error log; and NetErrorLogClear clears the error log and, optionally, saves the entries in a backup file.
NetErrorLogRead uses the ERROR_LOG data structure to read entries from and write entries to the error log. An entry consists of a fixed-length data structure. The data structure can be followed by UNICODE strings (el_text) that describe the error message, and a block of raw data (el_data) related to the cause of the error. Because of the variable lengths and structures of the el_data and el_text portions of the entry, only the fixed-length data structure is defined in the ERROR_LOG data structure.
The error log entry has the following format:
typedef struct _ERROR_LOG {
DWORD el_len;
DWORD el_reserved;
DWORD el_time;
DWORD el_error;
LPWSTR el_name
LPWSTR el_text;
LPBYTE el_data;
DWORD el_data_size;
DWORD el_nstrings;
} ERROR_LOG, *PERROR_LOG, *LPERROR_LOG;
/*
* Variable-length raw data specific to the error. el_len will be preceded by pad bytes
* as required for proper alignment. There may also be pad byes after the end of the
* fixed length structure, before el_data. Use the pointer in the fixed length structure
* to reference this data.
*/
BYTE el_data[]; /* Raw data */
DWORD el_len2;
The error log handle is defined as follows:
typedef struct _HLOG {
DWORD time;
DWORD last_flags;
DWORD offset;
DWORD rec_offset;
} HLOG, *PHLOG, *LPHLOG;
The error log APIs are:
4.16.1. NetErrorLogClear
NetErrorLogClear clears the error log and optionally saves the entries in a backup file.
Privilege Level
Admin privilege is required to successfully execute NetErrorLogClear on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetErrorLogClear (
IN LPWSTR server,
IN LPWSTR backupfile OPTIONAL,
IN LPBYTE reserved OPTIONAL
);
Parameters:
server __Points to an UNICODE string that contains the name of the server on which to execute NetErrorLogClear. A NULL pointer or NULL string specifies the local computer.
backupfile __Points to an UNICODE string that assigns a name for an optional backup file. The calling application must have write permission for the path specified by backupfile. A NULL pointer indicates not to back up the error log.
reserved __Reserved. Must be NULL.
4.16.2. NetErrorLogRead
NetErrorLogRead reads from the specified error log.
Privilege Level
No special privilege level is required to successfully execute NetErrorLogRead.
NET_API_STATUS NET_API_FUNCTION
NetErrorLogRead (
IN LPWSTR server,
IN LPWSTR reserved1 OPTIONAL,
IN LPHLOG errloghandle,
IN DWORD offset,
IN LPDWORD reserved2 OPTIONAL,
IN DWORD reserved3,
IN DWORD offsetflag,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD bytesread,
OUT LPDWORD totalbytes
);
Parameters:
server __Points to an UNICODE string that contains the name of the server on which to execute NetErrorLogClear. A NULL pointer or NULL string specifies the local computer.
reserved1 __Reserved. Must be NULL.
errloghandle __Points to the error log handle. An application calling NetErrorLogRead for the first time must initialize the 128-bit error log handle.
offset __Specifies the record offset at which to begin reading. This parameter is ignored unless bit 1 of offsetflag is set. If used, offset is taken as an offset of the record number (not bytes) at which to begin reading. Note that the record offset parameter is zero-based from both directions, depending upon the direction it is read.
reserved2 __Reserved. Must be NULL.
reserved3 __Reserved. Must be zero.
offsetflag __Specifies the open flags, bitmapped as follows:
Bit(s) Value
4.16.2.1. If 0, the log is read forward. If 1, the log
is read backward and records are returned in
reverse chronological order.
4.16.2.2. If 0, the read proceeds normally
(sequentially). If 1, the read proceeds from
the nth record from the start of the log,
where n is the offset parameter.
4.16.2.3. Reserved; must be 0.
bufptr __On return a pointer to the return information buffer is returned in the address pointed to by bufptr.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
bytesread __On return the actual number of bytes read into the buffer is located in the DWORD pointed to by bytesread.
totalbytes __On return the total bytes available to be read from the log is located in the DWORD pointed to by totalbytes.
4.17. Configuration APIs
These are only for downlevel support. Use the Registry APIs to retrieve configuration information on NT.
Configuration API functions retrieve network configuration information.
Configuration APIs are available at one information level.
NetConfigGet retrieves the value of a single specified entry for a particular component on the local computer or on a remote server.
Privilege Level
Admin privilege or accounts, comm, print, or server operator privilege is required to successfully execute NetConfigGet on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetConfigGet (
IN LPWSTR server,
IN LPWSTR component,
IN LPWSTR parameter,
OUT LPBYTE * bufptr
);
Parameters:
server __Points to an UNICODE string that contains the name of the server on which to execute NetConfigGet. A NULL pointer or NULL string specifies the local computer.
component __Points to an UNICODE string that specifies which configuration component to search.
parameter __Points to an UNICODE string that specifies the entry for the component specified whose value is to be returned.
bufptr __On return a pointer to the returned information is returned in the address pointed to by bufptr.
4.17.2. NetConfigGetAll
NetConfigGetAll retrieves all the configuration information for a given component on a local or a remote computer.
Privilege Level
Admin privilege or account, comm, print, or server operator privilege is required to successfully execute NetConfigGetAll on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetConfigGetAll (
IN LPWSTR server,
IN LPWSTR component,
OUT LPBYTE * bufptr
);
Parameters:
server __Points to an UNICODE string that contains the name of the server on which to execute NetConfigGet. A NULL pointer or NULL string specifies the local computer.
component __Points to an UNICODE string that specifies which configuration component to search.
bufptr __On return a pointer to the returned information is returned in the address pointed to by bufptr.
4.17.3. NetConfigSet
NetConfigSet sets the value of a single specified entry for a particular component on the local computer or on a remote server.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetConfigSet on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetConfigSet (
IN LPWSTR server,
IN LPWSTR reserved1 OPTIONAL,
IN LPWSTR component,
IN DWORD level,
IN DWORD reserved2,
IN LPBYTE buf,
IN DWORD reserved3
);
Parameters:
server __Points to an UNICODE string that contains the name of the server on which to execute NetConfigSet. A NULL pointer or NULL string specifies the local computer.
reserved1 __Reserved. Must be NULL.
component __Points to an UNICODE string that specifies which configuration component to set.
level __Infolevel of request. Must be zero.
reserved2 __Reserved. Must be zero.
buf __Buffer containing a CONFIG_INFO_0 structures.
reserved3 __Reserved. Must be zero.
4.18. Statistics APIs
LAN Manager accumulates a set of operating statistics for workstations and servers from the time that the Workstation or Server service is started. NetStatisticsGet is called to get those statistics. The Statistics API function, NetStatisticsGet, retrieves the operating statistics for workstations and servers. Since NT and downlevel workstations collect a different set of statistics, the caller must know whether the server is NT or downlevel (which can be discovered via the NetServerGetInfo API) and interpret the returned buffer accordingly.
The way lmstats.h is defined now, you can't define both an uplevel and downlevel structure without standing on your head (doing undef's etc). We need to fix this so both structures have unique names.
NetStatisticsGet returns a STAT_WORKSTATION_0 data structure when workstation statistics are requested; it returns a STAT_SERVER_0 data structure when server statistics are requested.
The downlevel STAT_WORKSTATION_0 data structure has this format:
NetStatisticsGet retrieves, and optionally clears, operating statistics for a service. Currently, only the Workstation and Server services are supported.
Privilege Level
Admin privilege or server operator privilege is required to successfully execute NetStatisticsGet on a remote server.
NET_API_STATUS NET_API_FUNCTION
NetStatisticsGet (
IN LPWSTR server,
IN LPWSTR service,
IN DWORD level,
IN DWORD options,
OUT LPBYTE * bufptr
);
Parameters:
server __Points to an UNICODE string that contains the name of the server on which to execute NetConfigGet. A NULL pointer or NULL string specifies the local computer.
service __Points to an UNICODE string that contains the name of the service about which to get the statistics. Only the values SERVER and WORKSTATION are currently allowed.
level __Specifies the level of detail requested; must be 0.
options __Specifies the options flags.
Bit(s) Meaning
4.18.1.1. Clear statistics.
4.18.1.2. Reserved; must be 0.
bufptr __On return a pointer to the returned information is returned in the address pointed to by bufptr.
4.19. Auditing APIs
These are for downlevel only. NT automatically records audits on failed accesses when AccessCheckAndAudit is used. To read audits, use the Eventlog ReadEventlog API.
Windows NT uses an integrated Eventlogging mechanism for reporting both errors and audits. The NetError and NetAudit APIs are provided to access downlevel LANMan logs. They will report ERROR_NOT_SUPPORTED if called to an Windows NT system.
Auditing API functions control the audit log. Auditing API functions monitor operations on the specified server. If auditing is enabled, each monitored operation generates an audit entry. For example, when a user establishes a connection to the server, a single audit entry is generated.
Audit entries are stored in a binary file called an audit trail or audit log. All Auditing API functions perform their operations on this file. LAN Manager defines many types of audit entries.
NetAuditRead reads the audit log. NetAuditClear clears the audit log.
Data Structures
All audit entries include a fixed-length header used in conjunction with variable-length data specific to the entry type. Because of the variable lengths and structures of the ae_data element of the audit entry (it is possible for ae_data to be zero bytes), only the fixed header is defined in the audit_entry data structure.
The variable-length portion of the audit entry can contain an offset to a variable-length UNICODE string. The offset values are DWORDs. To determine the value of the pointer to this string, add the offset value to the address of the ae_data data structure.
The following example illustrates this procedure. Assume that pAE points to a buffer that contains a complete audit entry and that the ae_type element of the audit_entry data structure contains the value AE_CONNSTOP, which specifies the predefined AE_CONNSTOP data structure. To point the variable pszComputerName to the UNICODE string that contains the name of the client whose connection was stopped, an application would perform the following algorithm:
/* Variable-length data specific to type of audit entry. There may be pad bytes after
ae_data_size for alignment purposes.
*/
BYTE ae_data[];
/* Terminating length indicator. Preceded by pad bytes for proper alignment.*/
DWORD ae_len2;
where
ae_len and ae_len2 Specify the length of the audit entry. Both have the same value. The ae_len element is included at the beginning and at the end of the audit entry to enable both backward and forward scanning of the log.
ae_reserved Reserved.
ae_time Specifies when the audit entry was generated. The value is stored as the number of seconds elapsed since 00:00:00, January 1, 1970.
ae_type Specifies the type of audit entry. Type values from 0x0000 through 0x07FF are reserved. OEMs and other applications programmers can reserve values from 0x0800 through 0xFFFF.
ae_data_offset Specifies the byte offset from the beginning of the audit entry to the beginning of the variable-length portion (ae_data) of the audit entry.
ae_data Specifies the variable-length portion of the audit entry; it differs depending on the type of entry specified by ae_type. The information begins at ae_data_offset bytes from the top of the audit entry. For information about the structure of each entry type defined by LAN Manager, see the following section.
Variable-Length Data
The following data structuresare specific to the audit entry type The structures follow the audit_entry header, but they are not necessarily contiguous.
The _AE_SRVSTATUS data structure is associated with an audit entry of type AE_SRVSTATUS.
typedef struct _AE_SRVSTATUS {
DWORD ae_sv_status;
}AE_SRVSTATUS , * PAE_SRVSTATUS ;
The _AE_SESSLOGON data structure is associated with an audit entry of type AE_SESSLOGON.
typedef struct _AE_SESSLOGON {
DWORD ae_so_compname;
DWORD ae_so_username;
DWORD ae_so_privilege;
}AE_SESSLOGON , * PAE_SESSLOGON ;
The _AE_SESSLOGOFF data structure is associated with an audit entry of type AE_SESSLOGOFF.
typedef struct ae_sesslogoff {
DWORD ae_sf_compname;
DWORD ae_sf_username;
DWORD ae_sf_reason;
}AE_SESSLOGOFF , * PAE_SESSLOGOFF;
The _AE_SESSPWERR data structure is associated with an audit entry of type AE_SESSPWERR.
typedef struct _AE_SESSPWERR {
DWORD ae_sp_compname;
DWORD ae_sp_username;
}AE_SESSPWERR , * PAE_SESSPWERR ;
The _AE_CONNSTART data structure is associated with an audit entry of type AE_CONNSTART.
typedef struct _AE_CONNSTART {
DWORD ae_ct_compname;
DWORD ae_ct_username;
DWORD ae_ct_netname;
DWORD ae_ct_connid;
}AE_CONNSTART , * PAE_CONNSTART ;
The _AE_CONNSTOP data structure is associated with an audit entry of type AE_CONNSTOP.
typedef struct _AE_CONNSTOP {
DWORD ae_cp_compname;
DWORD ae_cp_username;
DWORD ae_cp_netname;
DWORD ae_cp_connid;
DWORD ae_cp_reason;
}AE_CONNSTOP , * PAE_CONNSTOP ;
The _AE_CONNREJ data structure is associated with an audit entry of type AE_CONNREJ.
typedef struct _AE_CONNREJ {
DWORD ae_cr_compname;
DWORD ae_cr_username;
DWORD ae_cr_netname;
DWORD ae_cr_reason;
}AE_CONNREJ , * PAE_CONNREJ ;
The _AE_RESACCESS data structure is associated with an audit entry of type AE_RESACCESS.
typedef struct _AE_RESACCESS {
DWORD ae_ra_compname;
DWORD ae_ra_username;
DWORD ae_ra_resname;
DWORD ae_ra_operation;
DWORD ae_ra_returncode;
DWORD ae_ra_restype;
DWORD ae_ra_fileid;
}AE_RESACCESS , * PAE_RESACCESS ;
The _AD_RESACCESSREJ data structure is associated with an audit entry of type AE_RESACCESSREJ.
typedef struct _AE_RESACCESSREJ {
DWORD ae_rr_compname;
DWORD ae_rr_username;
DWORD ae_rr_resname;
DWORD ae_rr_operation;
}AE_RESACCESSREJ , * PAE_RESACCESSREJ ;
The _AD_CLOSEFILE data structure is associated with an audit entry of type AE_CLOSEFILE.
typedef struct _AE_CLOSEFILE {
DWORD ae_cf_compname;
DWORD ae_cf_username;
DWORD ae_cf_resname;
DWORD ae_cf_fileid;
DWORD ae_cf_duration
DWORD ae_cf_reason;
}AE_CLOSEFILE , * PAE_CLOSEFILE ;
The _AE_SERVICESTAT data structure is associated with an audit entry of type AE_SERVICESTAT.
typedef struct _AE_SERVICESTAT {
DWORD ae_ss_compname;
DWORD ae_ss_username;
DWORD ae_ss_svcname;
DWORD ae_ss_status;
DWORD ae_ss_code;
DWORD ae_ss_text;
DWORD ae_ss_returnval;
}AE_SERVICESTAT , * PAE_SERVICESTAT ;
The _AE_ACLMOD data structure is associated with audit entries of type AE_ACLMOD and AE_ACLMODFAIL.
struct _ae_aclmod {
DWORD ae_am_compname;
DWORD ae_am_username;
DWORD ae_am_resname;
DWORD ae_am_action;
DWORD ae_am_datalen;
}ae_aclmod, * Pae_aclmod;
The _AE_UASMOD data structure is associated with an audit entry of type AE_UASMOD.
typedef struct _AE_UASMOD {
DWORD ae_um_compname;
DWORD ae_um_username;
DWORD ae_um_resname;
DWORD ae_um_rectype;
DWORD ae_um_action;
DWORD ae_um_datalen;
}AE_UASMOD , * PAE_UASMOD ;
The _AE_NETLOGON data structure is associated with an audit entry of type AE_NETLOGON.
typedef struct _AE_NETLOGON {
DWORD ae_no_compname;
DWORD ae_no_username;
DWORD ae_no_privilege;
DWORD ae_no_authflags;
}AE_NETLOGON , * PAE_NETLOGON ;
The _AE_NETLOGOFF data structure is associated with an audit entry of type AE_NETLOGOFF.
typedef struct _AE_NETLOGOFF {
DWORD ae_nf_compname;
DWORD ae_nf_username;
DWORD ae_nf_reserved1;
DWORD ae_nf_reserved2;
}AE_NETLOGOFF , * PAE_NETLOGOFF ;
The _AE_ACCLIM data structure is associated with an audit entry of type AE_ACCLIMITEXCD.
typedef struct _AE_ACCLIM {
DWORD ae_al_compname;
DWORD ae_al_username;
DWORD ae_al_resname;
DWORD ae_al_limit;
}AE_ACCLIM , * PAE_ACCLIM ;
The _AE_LOCKOUT data structure is associated with an audit entry of type AE_LOCKOUT.
typedef struct ae_lockout {
DWORD ae_lk_compname;
DWORD ae_lk_username;
DWORD ae_lk_action;
DWORD ae_lk_bad_pw_count;
}ae_lockout , Pae_lockout ;
The _AE_GENERIC data structure is associated with an audit entry of type AE_GENERIC.
typedef struct _AE_GENERIC {
DWORD ae_ge_msgfile;
DWORD ae_ge_msgnum;
DWORD ae_ge_params;
DWORD ae_ge_param1;
DWORD ae_ge_param2;
DWORD ae_ge_param3;
DWORD ae_ge_param4;
DWORD ae_ge_param5;
DWORD ae_ge_param6;
DWORD ae_ge_param7;
DWORD ae_ge_param8;
DWORD ae_ge_param9;
}AE_GENERIC , * PAE_GENERIC ;
The audit log handle is defined as follows:
typedef struct _HLOG {
DWORD time;
DWORD last_flags;
DWORD offset;
DWORD rec_offset;
} HLOG, *PHLOG, *LPHLOG;
4.19.1. NetAuditClear
NetAuditClear clears the audit log on a server and, optionally, saves the entries in a backup file.
Privilege Level
Admin privilege is required to successfully execute NetAuditClear on a remote server or on a computer that has local security enabled.
NET_API_STATUS NET_API_FUNCTION
NetAuditClear (
IN LPWSTR server,
IN LPWSTR backupfile OPTIONAL,
IN LPWSTR service OPTIONAL
);
Parameters:
server __Points to an UNICODE string that contains the name of the server on which to execute NetAuditClear. A NULL pointer or NULL string specifies the local computer.
backupfile __Points to an UNICODE string that contains a name for the optional backup file. The calling application must have create and write permissions for the path specified by backupfile, and the path must already exist. If the pathname is relative, it is assumed to be relative to the LAN Manager LOGS directory. A NULL pointer specifies not to back up the audit log.
service __Points to an UNICODE string that contains the name of the service that owns the desired audit log to which the operation is to be performed.
4.19.2. NetAuditRead
NetAuditRead reads from the audit log on a server.
Privilege Level
Admin privilege or accounts, comm, print, or server operator privilege is required to successfully execute NetAuditRead on a remote server or on a computer that has local security enabled.
NET_API_STATUS NET_API_FUNCTION
NetAuditRead (
IN LPWSTR server,
IN LPWSTR service OPTIONAL,
IN LPHLOG auditloghandle,
IN DWORD offset,
IN LPDWORD reserved1 OPTIONAL,
IN DWORD reserved2,
IN DWORD offsetflag,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD bytesread,
OUT LPDWORD totalavailable
);
Parameters:
server __Points to an UNICODE string that contains the name of the server on which to execute NetAuditRead. A NULL pointer or NULL string specifies the local computer.
service __Points to an UNICODE string that contains the name of the service that owns the desired audit log to which the operation is to be performed.
auditloghandle __Points to the handle for the audit log. An application calling NetAuditRead for the first time must initialize the audit log handle as follows. The most significant bit (MSB) is the leftmost bit; the least significant bit (LSB) is the rightmost bit. After the first call, each call to NetAuditRead must be given the value for the handle returned by the previous call.
auditloghandle Value
4.19.2.1. (MSB) - 64 0
4.19.2.2. - 0 (LSB) 1
offset __Specifies the record offset at which to begin reading. This parameter is ignored unless bit 1 in the offsetflag parameter is set. If offsetflag bit 1 is set, offset is taken as an offset based on the record number (not bytes) at which the returned data should begin. Note that the record offset parameter is zero-based from both directions, depending upon the direction of the read. If reading backward, record 0 is the last record in the log. If reading forward, record 0 is the first record in the log.
reserved1 __Reserved. Must be NULL.
reserved2 __Reserved. Must be zero.
offsetflag __Specifies the open flags, as follows:
Bit(s) Meaning
4.19.2.3. If 0, the log is read forward. If 1, the log is
read backward and records are returned in the
buffer in reverse chronological order (newest
records first).
4.19.2.4. If 0, reading proceeds sequentially. If 1,
reading proceeds from the nth record from the
start of the log, where n is the offset
parameter.
4.19.2.5. Reserved; must be 0.
bufptr __On return a pointer to the returned information is returned in the address pointed to by bufptr. After a successful read operation, this buffer contains a sequence of audit entries with the accompanying variable-length data structures.
prefmaxlen __Prefered maximum length of returned data (in 8-bit bytes).
bytesread __On return the actual number of bytes read into the buffer is located in the DWORD pointed to by bytesread.
totalavailable __On return the total bytes available to be read from the log is located in the DWORD pointed to by totalavailable.
4.19.3. NetAuditWrite
This looks like a local only API. If so, remove it since these are for downlevel support only.
NetAuditWrite writes an audit entry to the local audit log.
Privilege Level
No special privilege level is required to successfully execute NetAuditWrite.
NET_API_STATUS NET_API_FUNCTION
NetAuditWrite (
IN DWORD type,
IN LPBYTE buf,
IN DWORD numbytes
IN LPWSTR service,
IN LPBYTE reserved,
);
Parameters:
type __Specifies the type of entry to write to the audit log.
buf __Points to a buffer that contains the data structure associated with the specified audit entry.
numbytes __Specifies the size (in bytes) of the buffer pointed to by buf.
service __Points to an UNICODE string that contains the name of the service that owns the desired audit log to which the operation is to be performed.
reserved __Reserved. Must be NULL.
4.20. Replicator APIs
The NT Replicator APIs control how the NT Replicator service updates selective directories from an export server to one or more clients. In addition to providing compatible LAN Manager 2.x functionality in a well-defined manner, this new set of LAN Manager APIs allow for specific API (operation) security checking.
The change from the file system based control on LAN Manager 2.x to Replicator API control on NT has the following implications:
o Applications can no longer delete a directory in the import path of a client to stop receiving updates from its master.
o Applications can no longer use the REPL.INI file in each replicated directory on a master to control the method of replication.
o Applications can no longer lock or unlock a directory on a master from being replicated by creating or deleting the USERLOCK.* file(s).
o Applications can no longer lock or unlock a directory on a client from receiving updates from its master by creating or deleting the USERLOCK.* file(s).
o Applications which depend on the LAN Manager 2.x behavior of ignoring locks for file integrity trees will need to be modified. (NT policy differs from LAN Manager 2.x policy; under NT the locks are always respected.)
Each of the intended operations listed above can be specified to the NT Replicator service through an appropriate API.
Any user or application which belongs to the admin or server operator group on a local or remote export server can modify the parameters which control the replication master.
There are three categories of Replicator APIs:
o Replicator Configuration APIs
o Replicator Export Directory APIs
o Replicator Import Directory APIs.
4.20.1. Replicator Configuration APIs
The configuration parameters of the Replicator service can be examined using NetReplGetInfo. They can be modified using NetReplSetInfo.
The Replicator service configuration parameters are:
role - Role of the Replicator service which is either REPL_ROLE_IMPORT (client), REPL_ROLE_EXPORT (master), or REPL_ROLE_BOTH. On a Advanced Server, any of these values are allowed. Under Windows/NT systems, only REPL_ROLE_IMPORT is allowed.
exportpath - Fully-qualified path name to the master tree in which directories are created and replicated from. This path must include the drive letter.
exportlist - List of machine and domain names to send update announcements to. If this list is not provided, then update announcements will be sent to the server's domain. The list entries are separated by semicolons; machine names in the list must not have leading backslashes
importpath - Fully-qualified path name to the client tree in which directories are created to receive the replicas of the master. This path must include the drive letter.
importlist - List of machines and domain names to receive updates from. If this list is not provided, then update announcements are received from the server's domain. The list entries are separated by semicolons; machine names in the list must not have leading backslashes.
logonusername - User account name belonging to the replicator group which the client logs on with to read files from its master(s). This field is ignored by the NT replicator, but is provided for possible future use.
interval - Time in minutes within which the master checks for changes in all the replicated directories. This field may be ignored by the NT replicator, but is provided for possible future use.
pulse - Time in number of intervals within which the master notifies its clients of the current replica version when no updates are necessary. This field may be ignored by the NT replicator, but is provided for possible future use.
guardtime - Time in minutes which a REPL_INTEGRITY_TREE level integrity directory must be stable before a client is allowed to update from it. (See explanation on integrity in section 4.20.2). The default guard time is 2 minutes.
random - A value in seconds sent by a master to its clients so that the clients can use the 0 - random range to generate a random time to wait on before updating from the master.
The configuration parameters (except the importpath and exportpath) values are all dynamically settable.
These APIs can be called whether the Replicator service is running or not. If the Replicator service is already running, any modification (except to the importpath and exportpath) to the replication configuration takes effect immediately, and is persistent after the Replicator service has been stopped. If the Replicator service is not started, the parameters are stored as persistent information and will take effect when the Replicator service starts up. The service must be stopped to set the importpath and exportpath values.
The Replicator configuration APIs information structures are:
NetReplGetInfo retrieves the Replicator service configuration information.
Security
No special group membership is required to successfully execute NetReplGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetReplGetInfo (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information required. Only level 0 is valid.
bufptr __On return a pointer to the return information structure is written in the address pointed to by bufptr.
4.20.2. NetReplSetInfo
NetReplSetInfo modifies the Replicator service configuration information.
Security
Admin or server operator group membership is required to successfully execute NetReplSetInfo.
NET_API_STATUS NET_API_FUNCTION
NetReplSetInfo (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information to set 0, 1000, 1001, 1002, and 1003 are valid levels.
buf __A pointer to a buffer containing the configuration information structure which corresponds to the specified level.
parm_err __Optional pointer to a DWORD to return the identifier of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.20.3. Replicator Export Directory APIs
The ReplExportDir APIs control top-level directories under the export path on the master. A user can create a new directory under the export path and the Replicator service will automatically replicate that directory. Or, a directory under the export path can be registered using NetReplExportDirAdd. When adding a directory to be replicated via these APIs, the replication controls (integrity and extent) are specified via the NetReplExportDirAdd API. If the directory is created in the file system and no replicator APIs are called, then the directory is treated as having file integrity and tree extent.
Integrity determines when a master updates a client. When integrity is REPL_INTEGRITY_FILE, the client gets a replica of a file within the directory when it is not in use (being changed or replicated). When integrity is set to REPL_INTEGRITY_TREE, every file and directory within the replicated directory must be stable for the amount of time specified by the guardtime parameter before the client is updated. Extent determines whether the entire tree within the directory is replicated (REPL_EXTENT_TREE) or only the files in the first-level directory is replicated (REPL_EXTENT_FILE).
The replication controls of each replicated directory can be examined using NetReplExportDirGetInfo, and dynamically modified using NetReplExportDirSetInfo. These control fields used to be specified in the REPL.INI file within each replicated directory on LAN Manager 2.x, and they were not dynamically settable. On NT, the REPL.INI file is not used and will be ignored in the replication process.
NetReplExportDirEnum returns a list of directories that are currently replicated. NetReplExportDirDel deregisters a directory so that it is no longer replicated.
The lock status information is returned in two fields: lockcount and locktime. Lockcount indicates the number of outstanding locks on a directory. Locktime is the time (in seconds since 1970, GMT) when the directory was first locked, or is 0 if the directory is not locked at the present time.
NetReplExportDirLock locks a directory so that it is not replicated, by incrementing a lock reference count for the directory. A lock on a directory can be unlocked using NetReplExportDirUnlock. The replication does not resume unless all outstanding locks on that directory are released, and the lock reference count is returned to 0. (The locktime field is automatically set to 0 when lockcount is 0.)
The ReplExportDir APIs can be called whether the Replicator service is running or not. If the Replicator service is running as a master, any modification to the directory controls takes effect immediately, and is persistent after the Replicator service has been stopped. If the Replicator service is not started, the controls for the directory is stored as persistent information and will take effect when the Replicator service starts up.
The ReplExportDir APIs are available at the following information levels:
NetReplExportDirAdd registers an existing directory in the export path to be replicated. The default values for locktime and lockcount (both 0) are assumed.
Security
Admin or server operator group membership is required to successfully execute NetReplExportDirAdd.
NET_API_STATUS NET_API_FUNCTION
NetReplExportDirAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information to add. Only level 1 is valid.
buf __A pointer to a buffer containing the directory control information structure.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.20.4. NetReplExportDirDel
NetReplExportDirDel deregisters a replicated directory.
Privilege Level
Security
Admin or server operator group membership is required to successfully execute NetReplExportDirDel.
NET_API_STATUS NET_API_FUNCTION
NetReplExportDirDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the name of a replicated directory to deregister.
4.20.5. NetReplExportDirEnum
NetReplExportDirEnum lists the replicated directories in the export path.
Security
No special group membership is required to successfully execute NetReplExportDirEnum.
NET_API_STATUS NET_API_FUNCTION
NetReplExportDirEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information to return. Levels 0,1, and 2 are valid.
bufptr __On return, an array of the specified information structure is returned in the address pointed to by bufptr.
prefmaxlen __Preferred maximum length of returned data (in 8-bit bytes). A value of 0xFFFFFFFF indicates that all available entries should be returned.
entriesread __On return, the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return, the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and 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, then no resume handle is stored.
4.20.6. NetReplExportDirGetInfo
NetReplExportDirGetInfo retrieves a replicated directory control information.
Security
No special group membership is required to successfully execute NetReplExportDirGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetReplExportDirGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the directory name to return control information about.
level __Level of information to return. Levels 0, 1, and 2 are valid.
bufptr __On return a pointer to the return information structure is written in the address pointed to by bufptr.
4.20.7. NetReplExportDirSetInfo
NetReplExportDirSetInfo modifies the control information of a replicated directory.
Security
Admin or server operator group membership is required to successfully execute NetReplExportDirSetInfo.
NET_API_STATUS NET_API_FUNCTION
NetReplExportDirSetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the directory name to return control information about.
level __Level of information to set. Levels 1, 1000, and 1001 are valid.
buf __A pointer to a buffer containing the control information structure which corresponds to the specified level.
parm_err __Optional pointer to a DWORD to return the identifier of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.20.7.1. NetReplExportDirLock
NetReplExportDirLock locks a replicated directory so that replication from it can be suspended. This function increments the lock reference count for the specified directory.
Security
Admin or server operator group membership is required to successfully execute NetReplExportDirLock.
NET_API_STATUS NET_API_FUNCTION
NetReplExportDirLock (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the directory name to lock.
4.20.7.2. NetReplExportDirUnlock
NetReplExportDirUnlock unlocks a directory so that replication from it can resume. This function decrements the lock reference count for the specified directory.
Security
Admin or server operator group membership is required to successfully execute NetReplExportDirUnlock.
NET_API_STATUS NET_API_FUNCTION
NetReplExportDirUnlock (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname,
IN DWORD unlockforce
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the directory name to unlock.
unlockforce __A value which indicates the force level to unlock the directory.
Force levels:
REPL_UNLOCK_NOFORCE - Unlocks the directory by decrementing the lock reference count. The lock reference count may or may not return to 0, so the directory could still be locked.
REPL_UNLOCK_FORCE - Unlocks the directory completely by removing all outstanding locks on the directory. The lock reference count is set to 0.
4.20.8. Replicator Import Directory APIs
The ReplImportDir APIs designate the top-level directories under the import path to receive updates on. They also return status information about a replicated directory on the client. On LAN Manager 2.x, a user must create a directory under the import path and the Replicator service automatically replicates to it. On NT, import directories are automatically added if they are exported by an export server from which importer is importing. Another way to register a directory in advance of it being exported, is to use the NetReplImportDirAdd API. This API does not create the directory itself. This is useful if you wish to modify some of the properties of the import directory (for example, to lock it) prior to it first beginning to import this directory.
NetReplImportDirDel deregisters a directory. This is used to clean up a directory that is no longer being exported. It will not stop replication if there is an active exporter, since it will be re-registered the next time the exporter tells the importer what directories it is exporting. If you wish to prevent importing of an actively exported directory, use the NetReplImportDirLock API.
NetReplImportDirEnum lists all the directories that are replicated to a client, and NetReplImportDirGetInfo returns the status of a specified directory.
The status information of a directory consists of the replication state, the UNC computername of the master (mastername), and the time (in seconds since 1970, GMT) when the directory was last updated (last_update_time). If the state is REPL_STATE_OK, the directory currently has a master, and is receiving regular update notices from it. If the state is REPL_STATE_NO_MASTER, the directory is not supported by any master, and it is normally empty. If the state is REPL_STATE_NO_SYNC, the directory has a master, but the master has not sent any update notices within the interval time period. This may be due to a communication failure, the master crashing, the directory being locked, files in the client directory being opened at update time, or an unstable REPL_INTEGRITY_TREE integrity directory on the master. If the client Replicator service is not started the state is REPL_STATE_NEVER_REPLICATED, mastername is a NULL string, and last_update_time is 0.NetReplImportDirLock locks a directory so that it does not receive updates, by incrementing a lock reference count for the directory. A lock on a directory can be unlocked using NetReplImportDirUnlock. The directory is not updated unless all outstanding locks on that directory are released, and the lock reference count is returned to 0.
The lock status information is returned in two fields: lockcount and locktime. Lockcount indicates the number of outstanding locks on a directory. Locktime is the time (in seconds since 1970, GMT) when the directory was first locked. (locktime is set to 0 whenever lockcount goes to 0.)
The ReplImportDir APIs can be called whether the Replicator service is running or not. If the Replicator service is running as a client, directory adds or deletes take effect immediately, and is persistent after the Replicator service has been stopped. If the Replicator service is not started, any added directory will receive updates when the Replicator service starts up (if there exists a master which exports the directory).
The ReplImportDir APIs are available at the following information levels:
NetReplImportDirAdd registers an existing directory in the import path to receive replication from a master.
Security
Admin or replicator group membership is required to successfully execute NetReplImportDirAdd.
NET_API_STATUS NET_API_FUNCTION
NetReplImportDirAdd (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
IN LPBYTE buf,
OUT LPDWORD parm_err OPTIONAL
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information to add. Only level 0 is valid.
buf __A pointer to a buffer containing the directory name.
parm_err __Optional pointer to a DWORD to return the index of the first parameter in error when ERROR_INVALID_PARAMETER is returned. If NULL the parameter is not returned on error.
4.20.9. NetReplImportDirDel
NetReplImportDirDel deregisters directory so that it no longer receives updates from the master. Note that this API does not actually delete the directory from the file system. Also, the directory may be automatically re-registered by the Replicator service at any time. To prevent importing of a directory that is being exported by some Replicator service, use the NetReplImportDirLock API instead.
Privilege Level
Security
Admin or replicator group membership is required to successfully execute NetReplImportDirDel.
NET_API_STATUS NET_API_FUNCTION
NetReplImportDirDel (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the name of a replicated directory to deregister.
4.20.10. NetReplImportDirEnum
NetReplImportDirEnum lists the replicated directories in the import path.
Security
No special group membership is required to successfully execute NetReplImportDirEnum.
NET_API_STATUS NET_API_FUNCTION
NetReplImportDirEnum (
IN LPWSTR servername OPTIONAL,
IN DWORD level,
OUT LPBYTE * bufptr,
IN DWORD prefmaxlen,
OUT LPDWORD entriesread,
OUT LPDWORD totalentries,
IN OUT LPDWORD resumehandle OPTIONAL
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
level __Level of information to return. Levels 0 or 1 are valid.
bufptr __On return, an array of the specified information structure is returned in the address pointed to by bufptr.
prefmaxlen __Preferred maximum length of returned data (in 8-bit bytes). A value of 0xFFFFFFFF indicates that all available entries should be returned.
entriesread __On return, the actual enumerated element count is located in the DWORD pointed to by entriesread.
totalentries __On return, the total number of entries that could have been enumerated from the current resume position is located in the DWORD pointed to by totalentries.
resumehandle __On return, a resume handle is stored in the DWORD pointed to by resumehandle, and 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, then no resume handle is stored.
4.20.11. NetReplImportDirGetInfo
NetReplImportDirGetInfo retrieves the status information on a client replicated directory.
Security
No special group membership is required to successfully execute NetReplImportDirGetInfo.
NET_API_STATUS NET_API_FUNCTION
NetReplImportDirGetInfo (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname,
IN DWORD level,
OUT LPBYTE * bufptr
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the directory name to return control information about.
level __Level of information to return. Levels 0 and 1 are valid.
bufptr __On return a pointer to the return information structure is written in the address pointed to by bufptr.
4.20.11.1. NetReplImportDirLock
NetReplImportDirLock locks a replicated directory so that replication to it can be suspended. This function increments the lock reference count for the specified directory.
Security
Admin or replicator group membership is required to successfully execute NetReplImportDirLock.
NET_API_STATUS NET_API_FUNCTION
NetReplImportDirLock (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the directory name to lock.
4.20.11.2. NetReplImportDirUnlock
NetReplImportDirUnlock unlocks a directory so that replication to it can resume. This function decrements the lock reference count for the specified directory.
Security
Admin or replicator group membership is required to successfully execute NetReplImportDirUnlock.
NET_API_STATUS NET_API_FUNCTION
NetReplImportDirUnlock (
IN LPWSTR servername OPTIONAL,
IN LPWSTR dirname,
IN DWORD unlockforce
);
Parameters:
servername __A pointer to a NULL terminated Unicode string containing the name of the remote server on which the function is to execute. A NULL pointer or string specifies the local machine.
dirname __A pointer to a NULL terminated Unicode string containing the directory name to unlock.
unlockforce __A value which indicates the force level to unlock the directory.
Force levels:
REPL_UNLOCK_NOFORCE - Unlocks the directory by decrementing the lock reference count. The lock reference count may or may not return to 0, so the directory could still be locked.
REPL_UNLOCK_FORCE - Unlocks the directory completely by removing all outstanding locks on the directory. The lock reference count is set to 0.
5. Lanman APIs That Are Not Supported In Windows NT
The following section lists the 16-bit LANMan APIs that are no longer supported in the 32-bit API set. In general, the rule we have followed is to not support anything that was marked as obsolete in LANMan 2.x. In addition, there are some APIs that no longer make sense in NT, and those have been removed as well. Another set of APIs has been folded into the NT base or Win32 API set .
5.2. APIs that only have support for remoting to downlevel
- NetAccess APIs
- NetAudit APIs
- NetConfig APIs
- NetError APIs
6. Interoperabilty Considerations
6.1. Requests From 16-bit LANMan Clients
NT provides support for most remote API called from downlevel clients. However, the following calls are NOT supported when remoted from a downlevel client to an NT server. In some of the below, there is a more current "2" version of the API which is supported (e.g. NetServerEnum).
NetFileEnum
NetFileGetInfo
NetFileClose
NetServerAdminCommand
NetAuditOpen
NetAuditClear
NetErrorLogOpen
NetErrorLogClear
NetMessageNameFwd
NetMessageNameUnFwd
NetMessageFileSend
NetMessageLogFileSet
NetMessageLogFileGet
NetUserAdd
NetUserSetInfo
NetUserPasswordSet
NetWkstaSetUID
NetUseEnum
NetUseAdd
NetUseDel
NetUseGetInfo
NetProfileSave
NetProfileLoad
NetStatisticsGet
NetStatisticsClear
NetNetBiosEnum
NetNetBiosGetInfo
NetServerEnum
NetConfigGet2
NetConfigGetAll2
NetHandleGetInfo
NetHandleSetInfo
NetAuditRead
NetUserValidate2
NetAccessCheck
NetAlertRaise
NetAlertStart
NetAlertStop
NetAuditWrite
NetServiceStatus
DosPrintDriverEnum
DosPrintQProcessorEnum
DosPrintPortEnum
DosPrintDest
NetConfigSet
6.2. Calling 16-bit LANMan Servers
When an RPC based API fails to connect to the appropriate interface the client-side stub may attempt to initiate a down-level API request to the server selected. For most of the Windows networking APIs 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 which offer new functionality the caller of the API should generally be aware of the destination type. When the new API offers a superset of the functionality of the down-level station the same API is used for both destinations, but the new API fields must have either a reserved value of an associated field to inform the conversion layer the field may be ignored if going downlevel. This is required so that an API caller is not misled as to the action performed when the API was called.
