3.5.4.6.2 NetrDatabaseSync2 (Opnum 16)

  • Article

The NetrDatabaseSync2 method SHOULD<222> return a set of all changes applied to the specified database since its creation. It provides an interface for a BDC to fully synchronize its databases to those of the PDC. Because returning all changes in one call might be prohibitively expensive due to a large amount of data being returned, this method supports retrieving portions of the database changes in a series of calls using a continuation context until all changes are received. It is possible for the series of calls to be terminated prematurely due to external events, such as system restarts. For that reason, the method also supports restarting the series of calls at a particular point specified by the caller. The caller MUST keep track of synchronization progress during the series of calls as detailed in this section.  

 NTSTATUS NetrDatabaseSync2(
   [in, string] LOGONSRV_HANDLE PrimaryName,
   [in, string] wchar_t* ComputerName,
   [in] PNETLOGON_AUTHENTICATOR Authenticator,
   [in, out] PNETLOGON_AUTHENTICATOR ReturnAuthenticator,
   [in] DWORD DatabaseID,
   [in] SYNC_STATE RestartState,
   [in, out] ULONG * SyncContext,
   [out] PNETLOGON_DELTA_ENUM_ARRAY* DeltaArray,
   [in] DWORD PreferredMaximumLength
 );

PrimaryName: The custom binding handle, as defined in section 3.5.4.1, that represents the connection to the PDC.

ComputerName: The null-terminated Unicode string that contains the NetBIOS name of the BDC calling this method.

Authenticator: A pointer to a NETLOGON_AUTHENTICATOR structure, as specified in section 2.2.1.1.5, that contains the client authenticator.

ReturnAuthenticator: A pointer to a NETLOGON_AUTHENTICATOR structure, as specified in section 2.2.1.1.5, that contains the server return authenticator.

DatabaseID: The identifier for a specific database for which the changes are requested. It MUST be one of the following values.

Value

Meaning

0x00000000

Indicates the SAM database.

0x00000001

Indicates the SAM built-in database.

0x00000002

Indicates the LSA database.

RestartState: Specifies whether this is a restart of the series of the synchronization calls and how to interpret SyncContext. This value MUST be NormalState unless this is the restart, in which case the value MUST be set as specified in the description of the SyncContext parameter.

SyncContext: Specifies context needed to continue the operation. The value MUST be set to zero on the first call. The caller MUST treat this as an opaque value, unless this call is a restart of the series of synchronization calls. The value returned is to be used on input for the next call in the series of synchronization calls.

If this call is the restart of the series, the values of the RestartState and the SyncContext parameters are dependent on the DeltaType value received on the last call before the restart and MUST be set as follows. Find the last NETLOGON_DELTA_ENUM structure in the DeltaArray parameter of the call. The DeltaType field of this NETLOGON_DELTA_ENUM structure, as specified in section 2.2.1.5.11, is the DeltaType needed for the restart. The values of RestartState and SyncContext are then determined from the following table.

DeltaType

RestartState

SyncContext

AddOrChangeGroup

GroupState

The value of the RID of the last element

AddOrChangeUser

UserState

The value of the RID of the last element

ChangeGroupMembership

GroupMemberState

The value of the RID of the last element

AddOrChangeAlias

AliasState

0x00000000

ChangeAliasMembership

AliasMemberState

0x00000000

Any other value not previously listed

NormalState

0x00000000

DeltaArray: A pointer to a NETLOGON_DELTA_ENUM_ARRAY structure, as specified in section 2.2.1.5.12, that contains an array of enumerated changes (deltas) to the specified database.

PreferredMaximumLength: The value that specifies the preferred maximum size, in bytes, of data referenced in the DeltaArray parameter. This is not a hard upper limit but serves as a guide to the server. The server SHOULD<223> stop including elements in the returned DeltaArray once the size of the returned data equals or exceeds the value of the PreferredMaximumLength parameter. It is up to the client implementation to choose the value for this parameter.

Return Values: The method returns 0x00000000 on success; otherwise, it returns a nonzero error code.

The server that receives this call MUST do the following:

  • Verify that the client is a backup domain controller (BDC), the server is a PDC, and is enabled. If any of these conditions are false, the server MUST return the status code STATUS_NOT_SUPPORTED.

  • Apply Common Error Processing Rule B, specified in section 3.

  • Using the ComputerName for the secure channel to find the corresponding record in the ClientSessionInfo table, verify the Authenticator parameter (section 3.1.4.5). If the Authenticator parameter is valid, compute the ReturnAuthenticator parameter returned (section 3.1.4.5). Otherwise, the server MUST return STATUS_ACCESS_DENIED.

  • Validate that DatabaseID is one of the allowed values, 0x00000000 through 0x00000002. If the DatabaseID is not one of these values, the server MUST return the status code STATUS_INVALID_LEVEL.

  • Given the RestartState parameter and the SyncContext parameter, obtain database records that are missing on the BDC and return the array of deltas, NETLOGON_DELTA_ENUM_ARRAY, for the missing records. The number of elements returned is affected by the value of the PreferredMaximumLength parameter. The server SHOULD<224> stop including elements in the returned array once the size of the returned data equals or exceeds the value of the PreferredMaximumLength parameter. The server SHOULD also limit the number of elements per local configuration to avoid large array allocations.

  • The server MUST update and return the SyncContext parameter (section 2.2.1.5.29) to continue the synchronization loop on the next client request.

  • Compute and return the server authenticator.

  • Initialize SynchronizationComplete by setting it to FALSE, and when all the missing records are sent set SynchronizationComplete to TRUE.

  • If SynchronizationComplete is FALSE, the server MUST return the status code STATUS_MORE_ENTRIES.