Directory Services

DsReplicaGetInfo

The DsReplicaGetInfo function retrieves replication state data from the directory service.

DWORD DsReplicaGetInfo(
  HANDLE hDS,
  DS_REPL_INFO_TYPE InfoType,
  LPCWSTR pszObject,
  UUID* puuidForSourceDsaObjGuid,
  VOID** ppInfo
);

Parameters

hDS
[in] Contains the bind handle to the directory service. This handle is returned by a call to the DsBind or DsBindWithCred function.
InfoType
[in] Contains one of the DS_REPL_INFO_TYPE values that specifies the type of replication data to retrieve. This value also determines which type of structure is returned in ppInfo.

Only the following values are supported for this function. If other data types are required, the DsReplicaGetInfo2 function must be used.

DS_REPL_INFO_NEIGHBORS
DS_REPL_INFO_CURSORS_FOR_NC
DS_REPL_INFO_METADATA_FOR_OBJ
DS_REPL_INFO_KCC_DSA_CONNECT_FAILURES
DS_REPL_INFO_KCC_DSA_LINK_FAILURES
DS_REPL_INFO_PENDING_OPS

pszObject
[in, optional] Pointer to a constant null-terminated Unicode string that identifies the object to retrieve replication data for. The meaning of this parameter depends on the value of the InfoType parameter. The following are possible value codes.
Value Meaning
DS_REPL_INFO_NEIGHBORS pszObject identifies the naming context for which replication neighbors are requested.
DS_REPL_INFO_CURSORS_FOR_NC pszObject identifies the naming context for which replication cursors are requested.
DS_REPL_INFO_METADATA_FOR_OBJ pszObject identifies the object for which replication metadata is requested.
DS_REPL_INFO_KCC_DSA_CONNECT_FAILURES pszObject must be NULL.
DS_REPL_INFO_KCC_DSA_LINK_FAILURES pszObject must be NULL.
DS_REPL_INFO_PENDING_OPS pszObject must be NULL.
puuidForSourceDsaObjGuid
[in, optional] Pointer to a GUID value that identifies a specific replication source. If this parameter is not NULL and the InfoType parameter contains DS_REPL_INFO_NEIGHBORS, only neighbor data for the source corresponding to the nTDSDSA object with the given objectGuid in the directory is returned. This parameter is ignored if NULL or if the InfoType parameter is anything other than DS_REPL_INFO_NEIGHBORS.
ppInfo
[out] Address of a structure pointer that receives the requested data. The value of the InfoType parameter determines the format of this structure. For more information and list of possible InfoType values and the corresponding structure types, see DS_REPL_INFO_TYPE.

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

Return Values

Returns ERROR_SUCCESS if successful or a Win32 or RPC error otherwise. The following are possible error codes.
Return Code Description
ERROR_INVALID_PARAMETER One or more parameters are invalid.
ERROR_NOT_SUPPORTED The requested version of the directory service server extensions is not supported.
ERROR_DS_DRA_ACCESS_DENIED The user associated with the credentials tied to hDS does not have sufficient privileges to read the requested replication state data. The user must have the Manage Replication Topology control access right on the root of the naming context containing pszObject, or the root of the local domain if pszObject is NULL.
ERROR_DS_DRA_BAD_DN pszObject is not an appropriate distinguished name.

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 only as Unicode.
Header: Declared in Ntdsapi.h.
Library: Use Ntdsapi.lib.

See Also

DsBind, DsBindWithCred, DsReplicaGetInfo2, DsReplicaFreeInfo, DS_REPL_INFO_TYPE, Domain Controller and Replication Management Functions