DsQuerySitesByCostA function (ntdsapi.h)

Article
02/22/2024

The DsQuerySitesByCost function gets the communication cost between one site and one or more other sites.

Syntax

NTDSAPI_POSTXP DWORD DsQuerySitesByCostA(
  [in]  HANDLE             hDS,
        LPSTR              pszFromSite,
        LPSTR              *rgszToSites,
  [in]  DWORD              cToSites,
  [in]  DWORD              dwFlags,
  [out] PDS_SITE_COST_INFO *prgSiteInfo
);

Parameters

[in] hDS

A directory service handle.

pszFromSite

Pointer to a null-terminated string that contains the relative distinguished name of the site the costs are measured from.

rgszToSites

Contains an array of null-terminated string pointers that contain the relative distinguished names of the sites the costs are measured to.

[in] cToSites

Contains the number of elements in the rgwszToSites array.

[in] dwFlags

Reserved.

[out] prgSiteInfo

Pointer to an array of DS_SITE_COST_INFO structures that receives the cost data. Each element in this array contains the cost data between the site identified by the pwszFromSite parameter and the site identified by the corresponding rgwszToSites element.

The caller must free this memory when it is no longer required by calling DsQuerySitesFree.

Return value

Returns ERROR_SUCCESS if successful or a Win32 or RPC error code otherwise. Possible error codes include values listed in the following list.

Remarks

The cost values obtained by this function are only used to compare and have no meaning by themselves. For example, the cost for site 1 can be compared to the cost for site 2, but the cost for site 1 cannot be compared to a fixed value.

Note

The ntdsapi.h header defines DsQuerySitesByCost 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	ntdsapi.h
Library	Ntdsapi.lib
DLL	Ntdsapi.dll