/*++ BUILD Version: 0001 Increment if a change has global effects
Copyright (c) 1998-1999 Microsoft Corporation
Module Name:
ntfrsapi.h
Abstract:
Header file for the application programmer's interfaces to the
File Replication Service (NtFrs) that support they system volumes
and DC Promotion / Demotion.
Environment:
User Mode - Win32
Notes:
--*/
#ifndef _NTFRSAPI_H_
#define _NTFRSAPI_H_
#ifdef __cplusplus
extern "C" {
#endif
//
// Pull in public headers for compat.
//
#include <frsapip.h>
//
// If a file or dir create has a name that starts with the following GUID
// then FRS does not replicate the created file or dir. Note: For dirs
// this means that the directory is never entered in the FRS directory filter
// table so FRS will never replicate the dir (even after it is renamed) or
// any changes to the dir (like ACLs or added streams or attrib changes) or
// any children created under the dir.
//
#define NTFRS_REPL_SUPPRESS_PREFIX L"2ca04e7e-44c8-4076-8890a424b8ad193e"
DWORD
WINAPI
NtFrsApi_PrepareForPromotionW(
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG) OPTIONAL
);
/*++
Routine Description:
The NtFrs service seeds the system volume during the promotion
of a server to a Domain Controller (DC). The files and directories
for the system volume come from the same machine that is supplying
the initial Directory Service (DS).
This function prepares the NtFrs service on this machine for
promotion by stopping the service, deleting old promotion
state in the registry, and restarting the service.
This function is not idempotent and isn't MT safe.
Arguments:
None.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_PrepareForDemotionUsingCredW(
IN SEC_WINNT_AUTH_IDENTITY *Credentials, OPTIONAL
IN HANDLE ClientToken,
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG) OPTIONAL
);
/*++
Routine Description:
The NtFrs service replicates the enterprise system volume to all
Domain Controllers (DCs) and replicates the domain system volume
to the DCs in a domain until the DC is demoted to a member server.
Replication is stopped by tombstoning the system volume's replica
set.
This function prepares the NtFrs service on this machine for
demotion by stopping the service, deleting old demotion
state in the registry, and restarting the service.
This function is not idempotent and isn't MT safe.
Arguments:
Credentials -- Credentionals to use in ldap binding call, if supplied.
ClientToken -- Impersonation token to use if no Credentials supplied.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_PrepareForDemotionW(
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG) OPTIONAL
);
/*++
Routine Description:
The NtFrs service replicates the enterprise system volume to all
Domain Controllers (DCs) and replicates the domain system volume
to the DCs in a domain until the DC is demoted to a member server.
Replication is stopped by tombstoning the system volume's replica
set.
This function prepares the NtFrs service on this machine for
demotion by stopping the service, deleting old demotion
state in the registry, and restarting the service.
This function is not idempotent and isn't MT safe.
Arguments:
None.
Return Value:
Win32 Status
--*/
#define NTFRSAPI_SERVICE_STATE_IS_UNKNOWN (00)
#define NTFRSAPI_SERVICE_PROMOTING (10)
#define NTFRSAPI_SERVICE_DEMOTING (20)
#define NTFRSAPI_SERVICE_DONE (99)
DWORD
WINAPI
NtFrsApi_StartPromotionW(
IN PWCHAR ParentComputer, OPTIONAL
IN PWCHAR ParentAccount, OPTIONAL
IN PWCHAR ParentPassword, OPTIONAL
IN DWORD DisplayCallBack(IN PWCHAR Display), OPTIONAL
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG), OPTIONAL
IN PWCHAR ReplicaSetName,
IN PWCHAR ReplicaSetType,
IN DWORD ReplicaSetPrimary,
IN PWCHAR ReplicaSetStage,
IN PWCHAR ReplicaSetRoot
);
/*++
Routine Description:
The NtFrs service seeds the system volume during the promotion
of a server to a Domain Controller (DC). The files and directories
for the system volume come from the same machine that is supplying
the initial Directory Service (DS).
This function kicks off a thread that updates the sysvol information
in the registry and initiates the seeding process. The thread tracks
the progress of the seeding and periodically informs the caller.
The threads started by NtFrsApi_StartPromotionW can be forcefully
terminated with NtFrsApi_AbortPromotionW.
The threads started by NtFrsApi_StartPromotionW can be waited on
with NtFrsApi_WaitForPromotionW.
Arguments:
ParentComputer - An RPC-bindable name of the computer that is
supplying the Directory Service (DS) with its
initial state. The files and directories for
the system volume are replicated from this
parent computer.
ParentAccount - A logon account on ParentComputer.
ParentPassword - The logon account's password on ParentComputer.
DisplayCallBack - Called periodically with a progress display.
ReplicaSetName - Name of the replica set.
ReplicaSetType - Type of replica set (enterprise or domain)
ReplicaSetPrimary - Is this the primary member of the replica set?
- 1 = primary; 0 = not.
ReplicaSetStage - Staging path.
ReplicaSetRoot - Root path.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_StartDemotionW(
IN PWCHAR ReplicaSetName,
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG) OPTIONAL
);
/*++
Routine Description:
The NtFrs service replicates the enterprise system volume to all
Domain Controllers (DCs) and replicates the domain system volume
to the DCs in a domain until the DC is demoted to a member server.
Replication is stopped by tombstoning the system volume's replica
set.
This function kicks off a thread that stops replication of the
system volume on this machine by telling the NtFrs service on
this machine to tombstone the system volume's replica set.
The threads started by NtFrsApi_StartDemotionW can be forcefully
terminated with NtFrsApi_AbortDemotionW.
The threads started by NtFrsApi_StartDemotionW can be waited on
with NtFrsApi_WaitForDemotionW.
Arguments:
ReplicaSetName - Name of the replica set.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_WaitForPromotionW(
IN DWORD TimeoutInMilliSeconds,
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG) OPTIONAL
);
/*++
Routine Description:
The NtFrs service seeds the system volume during the promotion
of a server to a Domain Controller (DC). The files and directories
for the system volume come from the same machine that is supplying
the initial Directory Service (DS).
This function waits for the seeding to finish or to stop w/error.
Arguments:
TimeoutInMilliSeconds - Timeout in milliseconds for waiting for
seeding to finish. INFINITE if no timeout.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_WaitForDemotionW(
IN DWORD TimeoutInMilliSeconds,
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG) OPTIONAL
);
/*++
Routine Description:
The NtFrs service replicates the enterprise system volume to all
Domain Controllers (DCs) and replicates the domain system volume
to the DCs in a domain until the DC is demoted to a member server.
Replication is stopped by tombstoning the system volume's replica
set.
This function waits for the tombstoning to finish or to stop w/error.
Arguments:
TimeoutInMilliSeconds - Timeout in milliseconds for waiting for
seeding to finish. INFINITE if no timeout.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_CommitPromotionW(
IN DWORD TimeoutInMilliSeconds,
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG) OPTIONAL
);
/*++
Routine Description:
WARNING - This function assumes the caller will reboot the system
soon after this call!
The NtFrs service seeds the system volume during the promotion
of a server to a Domain Controller (DC). The files and directories
for the system volume come from the same machine that is supplying
the initial Directory Service (DS).
This function waits for the seeding to finish, stops the service,
and commits the state in the registry. On reboot, the NtFrs Service
updates the DS on this machine with the information in the registry.
Arguments:
TimeoutInMilliSeconds - Timeout in milliseconds for waiting for
seeding to finish. INFINITE if no timeout.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_CommitDemotionW(
IN DWORD TimeoutInMilliSeconds,
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG) OPTIONAL
);
/*++
Routine Description:
WARNING - This function assumes the caller will reboot the system
soon after this call!
The NtFrs service replicates the enterprise system volume to all
Domain Controllers (DCs) and replicates the domain system volume
to the DCs in a domain until the DC is demoted to a member server.
Replication is stopped by tombstoning the system volume's replica
set.
This function waits for the tombstoning to finish, tells the service
to forcibly delete the system volumes' replica sets, stops the service,
and commits the state in the registry. On reboot, the NtFrs Service
updates the DS on this machine with the information in the registry.
Arguments:
TimeoutInMilliSeconds - Timeout in milliseconds for waiting for
tombstoning to finish. INFINITE if no timeout.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_AbortPromotionW(
VOID
);
/*++
Routine Description:
The NtFrs service seeds the system volume during the promotion
of a server to a Domain Controller (DC). The files and directories
for the system volume come from the same machine that is supplying
the initial Directory Service (DS).
This function aborts the seeding process by stopping the service,
deleting the promotion state out of the registry, cleaning up
the active threads and the active RPC calls, and finally resetting
the service to its pre-seeding state.
Arguments:
None.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_AbortDemotionW(
VOID
);
/*++
Routine Description:
The NtFrs service replicates the enterprise system volume to all
Domain Controllers (DCs) and replicates the domain system volume
to the DCs in a domain until the DC is demoted to a member server.
During demotion, NtFrsApi_StartDemotionW stops replication of
the system volume on this machine by telling the NtFrs service
on this machine to tombstone the system volume's replica set.
This function aborts the tombstoning process by stopping the service,
deleting the demotion state out of the registry, cleaning up
the active threads and the active RPC calls, and finally resetting
the service to its pre-tombstoning state.
Arguments:
None.
Return Value:
Win32 Status
--*/
//
// Type of internal information returned by NtFrsApi_InfoW()
//
#define NTFRSAPI_INFO_TYPE_MIN (0)
#define NTFRSAPI_INFO_TYPE_VERSION (0)
#define NTFRSAPI_INFO_TYPE_SETS (1)
#define NTFRSAPI_INFO_TYPE_DS (2)
#define NTFRSAPI_INFO_TYPE_MEMORY (3)
#define NTFRSAPI_INFO_TYPE_IDTABLE (4)
#define NTFRSAPI_INFO_TYPE_OUTLOG (5)
#define NTFRSAPI_INFO_TYPE_INLOG (6)
#define NTFRSAPI_INFO_TYPE_THREADS (7)
#define NTFRSAPI_INFO_TYPE_STAGE (8)
#define NTFRSAPI_INFO_TYPE_CONFIGTABLE (9)
#define NTFRSAPI_INFO_TYPE_MAX (10)
//
// Internal constants
//
#define NTFRSAPI_DEFAULT_INFO_SIZE (32 * 1024)
#define NTFRSAPI_MINIMUM_INFO_SIZE ( 1 * 1024)
//
// Opaque information from NtFrs.
// Parse with NtFrsApi_InfoLineW().
// Free with NtFrsApi_InfoFreeW();
//
typedef struct _NTFRSAPI_INFO {
ULONG Major;
ULONG Minor;
ULONG NtFrsMajor;
ULONG NtFrsMinor;
ULONG SizeInChars;
ULONG Flags;
ULONG TypeOfInfo;
ULONG TotalChars;
ULONG CharsToSkip;
ULONG OffsetToLines;
ULONG OffsetToFree;
CHAR Lines[1];
} NTFRSAPI_INFO, *PNTFRSAPI_INFO;
//
// RPC Blob must be at least this size
//
#define NTFRSAPI_INFO_HEADER_SIZE (5 * sizeof(ULONG))
//
// NtFrsApi Information Flags
//
#define NTFRSAPI_INFO_FLAGS_VERSION (0x00000001)
#define NTFRSAPI_INFO_FLAGS_FULL (0x00000002)
DWORD
WINAPI
NtFrsApi_InfoW(
IN PWCHAR ComputerName, OPTIONAL
IN ULONG TypeOfInfo,
IN ULONG SizeInChars,
IN OUT PVOID *NtFrsApiInfo
);
/*++
Routine Description:
Return a buffer full of the requested information. The information
can be extracted from the buffer with NtFrsApi_InfoLineW().
*NtFrsApiInfo should be NULL on the first call. On subsequent calls,
*NtFrsApiInfo will be filled in with more data if any is present.
Otherwise, *NtFrsApiInfo is set to NULL and the memory is freed.
The SizeInChars is a suggested size; the actual memory usage
may be different. The function chooses the memory usage if
SizeInChars is 0.
The format of the returned information can change without notice.
Arguments:
ComputerName - Poke the service on this computer. The computer
name can be any RPC-bindable name. Usually, the
NetBIOS or DNS name works just fine. The NetBIOS
name can be found with GetComputerName() or
hostname. The DNS name can be found with
gethostbyname() or ipconfig /all. If NULL, the
service on this computer is contacted. The service
is contacted using Secure RPC.
TypeOfInfo - See the constants beginning with NTFRSAPI_INFO_
in ntfrsapi.h.
SizeInChars - Suggested memory usage; actual may be different.
0 == Function chooses memory usage
NtFrsApiInfo - Opaque. Parse with NtFrsApi_InfoLineW().
Free with NtFrsApi_InfoFreeW();
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_InfoLineW(
IN PNTFRSAPI_INFO NtFrsApiInfo,
IN OUT PVOID *InOutLine
);
/*++
Routine Description:
Extract the wchar lines of information from NtFrsApiInformation.
Returns the address of the next L'\0' terminated line of information.
NULL if none.
Arguments:
NtFrsApiInfo - Opaque. Returned by NtFrsApi_InfoW().
Parse with NtFrsApi_InfoLineW().
Free with NtFrsApi_InfoFreeW().
Return Value:
Win32 Status
--*/
BOOL
WINAPI
NtFrsApi_InfoMoreW(
IN PNTFRSAPI_INFO NtFrsApiInfo
);
/*++
Routine Description:
All of the information may not have fit in the buffer. The additional
information can be fetched by calling NtFrsApi_InfoW() again with the
same NtFrsApiInfo struct. NtFrsApi_InfoW() will return NULL in
NtFrsApiInfo if there is no more information.
However, the information returned in subsequent calls to _InfoW() may be
out of sync with the previous information. If the user requires a
coherent information set, then the information buffer should be freed
with NtFrsApi_InfoFreeW() and another call made to NtFrsApi_InfoW()
with an increased SizeInChars. Repeat the procedure until
NtFrsApi_InfoMoreW() returns FALSE.
Arguments:
NtFrsApiInfo - Opaque. Returned by NtFrsApi_InfoW().
Parse with NtFrsApi_InfoLineW().
Free with NtFrsApi_InfoFreeW().
Return Value:
TRUE - The information buffer does *NOT* contain all of the info.
FALSE - The information buffer does contain all of the info.
--*/
DWORD
WINAPI
NtFrsApi_InfoFreeW(
IN PVOID *NtFrsApiInfo
);
/*++
Routine Description:
Free the information buffer allocated by NtFrsApi_InfoW();
Arguments:
NtFrsApiInfo - Opaque. Returned by NtFrsApi_InfoW().
Parse with NtFrsApi_InfoLineW().
Free with NtFrsApi_InfoFreeW().
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_DeleteSysvolMember(
IN PSEC_WINNT_AUTH_IDENTITY_W pCreds,
IN PWCHAR BindingDC,
IN PWCHAR NTDSSettingsDn,
IN OPTIONAL PWCHAR ComputerDn
);
/*++
Routine Description:
This API is written to be called from NTDSUTIL.EXE to remove
FRS member and subscriber object for a server that is being
removed (without dcpromo-demote) from the list of DCs.
Arguments:
pCreds p Credentials used to bind to the DS.
BindingDC - Name of a DC to perform the delete on.
NTDSSettingsDn - Dn of the "NTDS Settings" object for the server
that is being removed from the sysvol replica set.
ComputerDn - Dn of the computer object for the server that is
being removed from the sysvol replica set.
Return Value:
Win32 Status
--*/
#ifdef __cplusplus
}
#endif
#endif _NTFRSAPI_H_