The Win32 Network Management APIs 10

 

 

 

 

 

Requirements for Network Management Functions on Servers and Workstations

 

If you call one of the network management functions listed in this topic on a server or workstation, different access requirements apply to information queries and information updates.

 

Queries

 

If you call one of the following functions to perform a query on a server or workstation, by default, all authenticated users can read and enumerate the information.

 

  1. NetGroupEnum(), NetGroupGetInfo(), NetGroupGetUsers()
  2. NetLocalGroupEnum(), NetLocalGroupGetInfo(), NetLocalGroupGetMembers()
  3. NetQueryDisplayInformation()
  4. NetSessionGetInfo() (levels 1 and 2 only)
  5. NetShareEnum() (levels 2 and 502 only)
  6. NetUserEnum(), NetUserGetGroups(), NetUserGetInfo(), NetUserGetLocalGroups(), NetUserModalsGet()
  7. NetWkstaGetInfo(), NetWkstaUserEnum()

 

For Windows Server 2003 and Windows XP:  Anonymous access to information is possible if the EveryoneIncludesAnonymous policy setting allows anonymous access. For Windows 2000:  Anonymous access to securable objects is possible if the RestrictAnonymous policy setting allows anonymous access. You can restrict anonymous access by setting the following key in the registry to the value 1.

 

HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\Lsa\RestrictAnonymous = 1

 

For more information, see the following article in the Microsoft Knowledge Base: ARTICLE ID: Q246261 - TITLE: How to use the RestrictAnonymous registry Value.

 

Updates

 

By default, only Administrators and Power Users can write information.

 

Mapping ADSI Interfaces to the Network Management Functions

 

The Active Directory Service Interfaces (ADSI) are a set of COM interfaces used to access the capabilities of directory services from different network providers. ADSI presents a single set of directory service interfaces for managing network resources in a distributed computing environment. If you are programming for Active Directory, you may be able to call certain ADSI interface methods to achieve the same functionality you can achieve by calling certain network management functions. The following table lists network management functions and function groups, and the ADSI interfaces to which the functions map.

 

Functions

Interfaces

NetFileEnum(), NetFileGetInfo()

IADsResource(), IADsFileServiceOperations()

NetGroup*

IADsGroup()

NetLocalGroup*

IADsGroup()

NetServer*

IADsComputer()

NetSession*

IADsSession(), IADsFileServiceOperations()

NetShare*

IADsFileShare()

NetUser*

IADsUser(), IADsComputer()

NetUserModals*

IADsDomain()

 

Network Management Data

 

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

 

Network Management Function Buffers

 

The RPC run-time library handles the buffers required by the 32-bit data retrieval network management functions as follows:

 

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

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

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

The system allocates the buffer for the returned information. The caller must pass a pointer variable to the function on input. On successful return, the pointer receives the address of the system-allocated buffer that contains the returned information. This simplifies the calling code, because the caller does not need to estimate the size of the buffer, or resize the buffer and reissue the function. When the caller has finished processing the returned information, it must free the system-allocated memory by calling the NetApiBufferFree() function. Example: NetGroupEnum()

 

Network Management Function Buffer Lengths

 

This topic discusses the requirements for function buffer lengths when used with the network management APIs. Applications that specify buffer sizes when calling network management enumeration functions (and various data retrieval functions) must specify buffers large enough to hold the returned information structure (or structures) plus the strings to which their members point. If you do not specify a large enough buffer to receive all the available entries, the function returns ERROR_MORE_DATA. Enumeration calls do not return partial entries. Some network management functions take an advisory maximum data-length parameter, prefmaxlen. This parameter allows an application to suggest the number of bytes the server should return from a function call. If you specify the value MAX_PREFERRED_LENGTH in the prefmaxlen parameter, the network management functions allocate the amount of memory required for the data.

 

API Data Alignment

 

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

 

DFS Server Target Prioritization

 

DFS Server Target Prioritization is a feature available in Microsoft Windows Server 2003 with Service Pack 1 (SP1) and later operating systems. This feature enables DFS servers to take advantage of available Active Directory site-cost information to prioritize the targets in client referrals. Before Windows Server 2003 with SP1, targets were grouped into two sets: one group for containing all targets in the same site as the client; and another group for all other targets. Those targets sharing the same site as the client are called "in-site", and if site-costing is enabled, they are assigned a specific cost value relative to the site overall, with lower site costs preferred over higher ones. With the availability of this site-costing data, server targets can be prioritized for more effective DFS server failover strategies. In the past, this granular level of detail was not available, and administrators had to resort to artificial means (such as dummy sites in AD) to support even simple requirements like the designation of specific servers as a "backup" or "secondary" server in the case where a "primary" DFS server fails. Now, with the additional detail provided by site-costing, multi-level failover strategies are possible. The following discussion assumes that site-costing is enabled.

 

DFS Server Target Prioritization

 

Target priority is a specific ordering from an administrative perspective, classifying and ranking in-site servers in terms of explicit preference based on their site cost from a DFS client. Global priority is independent of the site-cost. Note that global priority classes don't necessarily indicate the most optimal targets from a DFS client's perspective, but instead reflect the importance, or lack of importance, of specific targets from a site administrator's perspective. Server target priority is divided into two value categories: priority class and priority rank. Priority classes are divided into two levels: local and global. Within these classes there is a rough ordering of targets based on site cost, grouped as high, normal, and low priority. The result is five priority classes, in order from highest to lowest priority as follows:

 

  1. Global high priority
  2. Site-cost high priority
  3. Site-cost normal priority
  4. Site-cost low priority
  5. Global low priority

 

The site-cost classes can be considered as subdivisions of "global normal priority". Priority rank is a simple integer ranking based on ordinal values: 0, 1, 2, and onward, with 0 being the highest value and all subsequent values indicating decreasing rank. The global high and low priorities do not consider site-cost values. Targets with a global high priority receive preference over all other targets, and targets with a global low priority receive the least preference. In ordering a referral, the complete process has the following steps:

 

  1. The sets of global high and low targets are identified, along with the remaining "global normal" targets.
  2. If the "INSITE" option is set, all targets outside of the client's site are removed. The "INSITE" option is not applied to the global high and low priority sets.
  3. Within each of these three sets, the targets are ordered using the AD site-cost mechanism, using either local or full site costing. The result is sets of targets of equal site cost.
  4. Within the sets of "global normal" targets of equal site cost, targets are assigned a priority class from the site-cost high, normal, and low priority rankings.
  5. Within the sets of targets of equal site cost and priority class, targets are now ordered by priority rank, with 0 being the highest rank.
  6. Within the sets of targets of equal site cost, priority class, and priority rank, targets are randomly shuffled for load balancing.

 

Graphically, a set of targets are ordered as seen below:

 

  1. global high priority class targets
  2. site-cost high priority class targets with site cost = 0
  3. normal with site cost = 0
  4. low with site cost = 0
  5. site-cost high priority class targets with site cost = 1
  6. normal with site cost = 1
  7. low with site cost = 1
  8. and so on
  9. global low priority class targets

 

Within each of these sets, targets are sorted according to priority rank. The highest rank is zero, with each subsequent integer value (1, 2, and so on) indicating an increasingly lower rank. Target priority is set on a specific target of a link (or root) in a DFS namespace. A target's priority for one link does not influence the ordering of other links if that same target path is used multiple times. For example, if two links have \\server\share1 as a target, the priority of \\server\share1 is set separately for both links. The default priority for all links is the site-cost normal priority with a rank of 0. Target priority does not affect the ordering of referrals unless it is used, and all existing links are ordered as they are received.

The referral response from a DFS server consists of target sets ordered as indicated above, with each non-global target set containing targets of the same site cost, priority class, and priority rank. Targets within each set are ordered randomly. DFS clients that receive the referral start with the first target of the first set, and continue through the list until an available target for a given DFS root or link is found. For the specific API implementation of this feature, please see the following reference topics:

 

  1. DFS_INFO_6
  2. DFS_INFO_104
  3. DFS_INFO_106
  4. DFS_TARGET_PRIORITY
  5. DFS_TARGET_PRIORITY_CLASS

 

 

 

 

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