Directory Services

DsQuerySitesByCost

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

DWORD DsQuerySitesByCost(
  HANDLE hDS,
  LPTSTR pwszFromSite,
  LPTSTR* rgwszToSites,
  DWORD cToSites,
  DWORD dwFlags,
  PDS_SITE_COST_INFO* prgSiteInfo
);

Parameters

hDS
[in] Contains a binding handle obtained with the DsBindToISTG function.
pwszFromSite
[in] Pointer to a null-terminated string that contains the relative distinguished name of the site the costs are measured from. The case of this name must exactly match the case of the site or this function will return ERROR_DS_OBJ_NOT_FOUND.
rgwszToSites
[in] Contains an array of null-terminated string pointers that contain the relative distinguished names of the sites the costs are measured to. The case of these names must exactly match the case of the site or this function will return ERROR_DS_OBJ_NOT_FOUND.
cToSites
[in] Contains the number of elements in the rgwszToSites array.
dwFlags
[in] Not currently used.
prgSiteInfo
[out] 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 Values

Returns ERROR_SUCCESS if successful or a Win32 or RPC error code otherwise. Possible error codes include the following values.
Return Code Description
ERROR_DS_OBJ_NOT_FOUND The site represented by the pwszFromSite parameter or one or more of the sites in the rgwszToSites array cannot be found.
ERROR_INVALID_PARAMETER one or more parameters are invalid.
ERROR_NOT_ENOUGH_MEMORY A memory allocation failure occurred.

Remarks

The cost values obtained by this function are only used to compare against one another 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.

Requirements

Client: Included in Windows XP and Windows 2000 Professional.
Server: Included in Windows Server 2003 and Windows 2000 Server.
Redistributable: Requires Active Directory Client Extension on Windows NT 4.0 SP6a and Windows 95/98/Me.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000/XP.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

DsBindToISTG, DS_SITE_COST_INFO, DsQuerySitesFree, Domain Controller and Replication Management Functions