DsReplicaSyncAllA function (ntdsapi.h)

Article
02/09/2023

The DsReplicaSyncAll function synchronizes a server with all other servers, using transitive replication, as necessary. By default, DsReplicaSyncAll synchronizes the server with all other servers in its site; however, you can also use it to synchronize across site boundaries.

Syntax

NTDSAPI DWORD DsReplicaSyncAllA(
  [in]            HANDLE                                  hDS,
  [in]            LPCSTR                                  pszNameContext,
  [in]            ULONG                                   ulFlags,
  [in]            BOOL(* )(LPVOID,PDS_REPSYNCALL_UPDATEA) pFnCallBack,
  [in, optional]  LPVOID                                  pCallbackData,
  [out, optional] PDS_REPSYNCALL_ERRINFOA                 **pErrors
);

Parameters

[in] hDS

Contains a directory service handle obtained from either the DSBind or DSBindWithCred function.

[in] pszNameContext

Pointer to a null-terminated string that specifies the distinguished name of the naming context to synchronize. The pszNameContext parameter is optional; if its value is NULL, the configuration naming context is replicated.

[in] ulFlags

Passes additional data used to process the request. This parameter can be a combination of the following values.

DS_REPSYNCALL_ABORT_IF_SERVER_UNAVAILABLE

Generates a fatal error if any server cannot be contacted or if any server is unreachable due to a disconnected or broken topology.

DS_REPSYNCALL_CROSS_SITE_BOUNDARIES

Synchronizes across site boundaries. By default, DsReplicaSyncAll attempts to synchronize only with DCs in the same site as the home system. Set this flag to attempt to synchronize with all DCs in the enterprise forest. However, the DCs can be synchronized only if connected by a synchronous (RPC) transport.

DS_REPSYNCALL_DO_NOT_SYNC

Disables all synchronization. The topology is still analyzed, and unavailable or unreachable servers are still identified.

DS_REPSYNCALL_ID_SERVERS_BY_DN

In the event of a non-fatal error, returns server distinguished names (DN) instead of their GUID DNS names.

DS_REPSYNCALL_NO_OPTIONS

This option has no effect.

DS_REPSYNCALL_PUSH_CHANGES_OUTWARD

Pushes changes from the home server out to all partners using transitive replication. This reverses the direction of replication, and the order of execution of the replication sets from the usual "pulling" mode of execution.

DS_REPSYNCALL_SKIP_INITIAL_CHECK

Assumes that all servers are responding. This speeds operation of the DsReplicaSyncAll function, but if some servers are not responding, some transitive replications may be blocked.

DS_REPSYNCALL_SYNC_ADJACENT_SERVERS_ONLY

Disables transitive replication. Synchronization is performed only with adjacent servers.

[in] pFnCallBack

Pointer to an application-defined SyncUpdateProc function called by the DsReplicaSyncAll function when it encounters an error, initiates synchronization of two servers, completes synchronization of two servers, or finishes synchronization of all the servers in the site.

[in, optional] pCallbackData

Pointer to application-defined data passed as the first argument of the SyncUpdateProc callback function pointed to by the pFnCallBack parameter.

[out, optional] pErrors

A NULL-terminated array of pointers to
DS_REPSYNCALL_ERRINFO structures that contain errors that occurred during synchronization. The memory used to hold both the array of pointers and the MsCS\mscs\clusctl_resource_type_get_private_property_fmts.xml data is allocated as a single block of memory and should be freed when no longer required by a single call to LocalFree with the pointer value returned in pErrors used as the argument.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is as follows.

Remarks

The DsReplicaSyncAll function attempts to bind to all servers before generating a topology to synchronize from. If a server cannot be contacted, the function excludes that server from the topology and attempts to work around it. Setting the DS_REPSYNCALL_SKIP_INITIAL_CHECK flag in ulFlags bypasses the initial binding.

If a server cannot be contacted, the DsReplicaSyncAll function attempts to route around it and replicate from as many servers as possible, unless DS_REPSYNCALL_ABORT_IF_SERVER_UNAVAILABLE is set in ulFlags.

The DsReplicaSyncAll function can use the callback function pointed to by pFnCallBack to keep an end user informed about the current status of the replication. Execution of the DsReplicaSyncAll function pauses when it calls the function pointed to by pFnCallBack. If the return value from the callback function is TRUE, replication continues; otherwise, the DsReplicaSyncAll function terminates replication.

Note

The ntdsapi.h header defines DsReplicaSyncAll 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