DsQuerySitesByCost

DsQuerySitesByCost function

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

Syntax


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

Parameters

hDS [in]

A directory service handle.

pwszFromSite [in]

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

rgwszToSites [in]

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

cToSites [in]

Contains the number of elements in the rgwszToSites array.

dwFlags [in]

Reserved.

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 value

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

Return codeDescription
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 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

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Ntdsapi.h

Library

Ntdsapi.lib

DLL

Ntdsapi.dll

Unicode and ANSI names

DsQuerySitesByCostW (Unicode) and DsQuerySitesByCostA (ANSI)

See also

Domain Controller and Replication Management Functions
DS_SITE_COST_INFO
DsQuerySitesFree

 

 

Show:
© 2016 Microsoft