DsReplicaAdd

The DsReplicaAdd function adds a replication source reference to a destination naming context (NC).

DWORD DsReplicaAdd(
  HANDLE hDS,
  LPCTSTR NameContext,
  LPCTSTR SourceDsaDn,
  LPCTSTR TransportDn,
  LPCTSTR SourceDsaAddress,
  const PSCHEDULE pSchedule,
  DWORD Options
);

Parameters

hDS

[in] Bind handle to the directory service.

NameContext

[in] Pointer to a constant null-terminated Unicode string specifying the distinguished name (DN) of the destination naming context (NC) for which to add the replica. The destination NC record must exist locally as either an object (instantiated or not) or a reference phantom (for example, a phantom with a GUID).

SourceDsaDn

[in] Pointer to a constant null-terminated Unicode string specifying the DN of the NTDSDSA object for the source directory system agent. This parameter is required if Options includes DS_REPADD_ASYNCHRONOUS_REPLICA; otherwise, it is ignored.

TransportDn

[in] Pointer to a constant null-terminated Unicode string specifying the DN of the interSiteTransport object representing the transport to be used for communication with the source server. This parameter is required if Options includes DS_REPADD_INTERSITE_MESSAGING; otherwise, it is ignored.

SourceDsaAddress

[in] Pointer to a constant null-terminated Unicode string specifying the transport-specific address of the source DSA. This source server is identified by a string name, not by its UUID. A string name appropriate for SourceDsaAddress will usually be a domain name service (DNS) name based on a GUID, where the GUID part of the name is the GUID of the NTDSDSA object for the source server.

pSchedule

[in] Pointer to the schedule for this replica.

Options

[in] Passes additional information to be used to process the request. This parameter can be a combination of the following values.

Value	Meaning
DS_REPADD_ASYNCHRONOUS_OPERATION	Performs this operation asynchronously.
DS_REPADD_ASYNCHRONOUS_REPLICA	Does not replicate the NC now. Instead, save enough state such that it may be replicated later.
DS_REPADD_DISABLE_NOTIFICATION	Disables notification-based synchronization for the NC from this source. This is expected to be a temporary state. Use DS_REPADD_NEVER_NOTIFY to disable synchronization permanently.
DS_REPADD_DISABLE_PERIODIC	Disables periodic synchronization for the NC from this source.
DS_REPADD_INITIAL	Synchronizes the NC from this source when the DSA is started.
DS_REPADD_INTERSITE_MESSAGING	Synchronizes from the source DSA using the Intersite Messaging Service (IMS) transport (for example, by SMTP) rather than using the native directory service RPC.
DS_REPADD_NEVER_NOTIFY	Disables change notifications from this source. When this flag is set, the source will not notify the destination when changes occur. This is recommended for all intersite replication that may occur over WAN links. This is expected to be a permanent state; use DS_REPADD_DISABLE_NOTIFICATION to temporarily disable notifications.
DS_REPADD_PERIODIC	Synchronizes the NC from this source periodically, as defined in pSchedule.
DS_REPADD_USE_COMPRESSION	Uses compression when replicating. This saves network bandwidth at the expense of CPU overhead at both the source and destination servers.
DS_REPADD_WRITEABLE	Creates a writeable replica; otherwise, the replica will be read-only.

Return Values

If the function performs its operation successfully, the return value is ERROR_SUCCESS.

If the function fails, the return value can be one of the following.

ERROR_INVALID_PARAMETER

A parameter is incorrect.

ERROR_NOT_SUPPORTED

The requested version of the directory service server extensions is not supported.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Ntdsapi.h.
  Library: Included as a resource in Ntdsapi.dll.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

See Also

DC and Replication Management Functions, DsReplicaDel, DsReplicaModify, DsReplicaSync, DsReplicaSyncAll, DsReplicaUpdateRefs