DsAddressToSiteNamesExA function (dsgetdc.h)

Article
02/09/2023

The DsAddressToSiteNamesEx function obtains the site and subnet names corresponding to the addresses specified.

Syntax

DSGETDCAPI DWORD DsAddressToSiteNamesExA(
  [in, optional] LPCSTR          ComputerName,
  [in]           DWORD           EntryCount,
  [in]           PSOCKET_ADDRESS SocketAddresses,
  [out]          LPSTR           **SiteNames,
  [out]          LPSTR           **SubnetNames
);

Parameters

[in, optional] ComputerName

Pointer to a null-terminated string that specifies the name of the remote server to process this function. This parameter must be the name of a domain controller. A non-domain controller can call this function by calling DsGetDcName to find the domain controller.

[in] EntryCount

Contains the number of elements in the SocketAddresses array.

[in] SocketAddresses

Contains an array of SOCKET_ADDRESS structures that contain the addresses to convert. Each address in this array must be of the type AF_INET. EntryCount contains the number of elements in this array.

[out] SiteNames

Receives an array of null-terminated string pointers that contain the site names for the addresses. Each element in this array corresponds to the same element in the SocketAddresses array. An element is NULL if the corresponding address does not map to any known site or if the address entry is not of the proper form. The caller must free this array when it is no longer required by calling NetApiBufferFree.

[out] SubnetNames

Receives an array of null-terminated string pointers that contain the subnet names used to perform the address to site name mappings. Each element in this array corresponds to the same element in the SocketAddresses array. An element is NULL if the corresponding address to site name mapping was not determined or if no subnet was used to perform the corresponding address to site mapping. The latter will be the case when there is exactly one site in the enterprise with no subnet objects mapped to it. The caller must free this array when it is no longer required by calling NetApiBufferFree.

Return value

Returns NO_ERROR if successful or a Win32 or RPC error otherwise. The following are possible error codes.

Remarks

Note

The dsgetdc.h header defines DsAddressToSiteNamesEx as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista
Minimum supported server	Windows Server 2008
Target Platform	Windows
Header	dsgetdc.h
Library	Netapi32.lib
DLL	Netapi32.dll