able/windows-nt
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity
windows-nt/Source/XPSP1/NT/published/sdk/inc/frsapip.h

569 lines
18 KiB
C
Raw Normal View History

Add source files
2020-09-26 03:20:57 -05:00
/*++ BUILD Version: 0001 Increment if a change has global effects
Copyright (c) 1998-1999 Microsoft Corporation
Module Name:
frsapip.h
Abstract:
Header file for the application programmer's interfaces to the
Microsoft File Replication Service (NtFrs).
These APIs provide support for backup and restore.
Environment:
User Mode - Win32
Notes:
--*/
#ifndef _FRSAPIP_H_
#define _FRSAPIP_H_
#ifdef __cplusplus
extern "C" {
#endif
//
// Replica set types.
//
#define NTFRSAPI_REPLICA_SET_TYPE_ENTERPRISE L"Enterprise"
#define NTFRSAPI_REPLICA_SET_TYPE_DOMAIN L"Domain"
#define NTFRSAPI_REPLICA_SET_TYPE_DFS L"DFS"
#define NTFRSAPI_REPLICA_SET_TYPE_OTHER L"Other"
//
// BACKUP/RESTORE API
//
#define NTFRSAPI_BUR_FLAGS_NONE (0x00000000)
#define NTFRSAPI_BUR_FLAGS_AUTHORITATIVE (0x00000001)
#define NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE (0x00000002)
#define NTFRSAPI_BUR_FLAGS_PRIMARY (0x00000004)
#define NTFRSAPI_BUR_FLAGS_SYSTEM (0x00000008)
#define NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY (0x00000010)
#define NTFRSAPI_BUR_FLAGS_NORMAL (0x00000020)
#define NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES (0x00000040)
#define NTFRSAPI_BUR_FLAGS_RESTORE (0x00000080)
#define NTFRSAPI_BUR_FLAGS_BACKUP (0x00000100)
#define NTFRSAPI_BUR_FLAGS_RESTART (0x00000200)
#define NTFRSAPI_BUR_FLAGS_TYPES_OF_RESTORE \
(NTFRSAPI_BUR_FLAGS_AUTHORITATIVE | \
NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE | \
NTFRSAPI_BUR_FLAGS_PRIMARY)
#define NTFRSAPI_BUR_FLAGS_MODES_OF_RESTORE \
(NTFRSAPI_BUR_FLAGS_SYSTEM | \
NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY | \
NTFRSAPI_BUR_FLAGS_NORMAL)
#define NTFRSAPI_BUR_FLAGS_SUPPORTED_RESTORE \
(NTFRSAPI_BUR_FLAGS_AUTHORITATIVE | \
NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE | \
NTFRSAPI_BUR_FLAGS_PRIMARY | \
NTFRSAPI_BUR_FLAGS_SYSTEM | \
NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY | \
NTFRSAPI_BUR_FLAGS_NORMAL | \
NTFRSAPI_BUR_FLAGS_RESTORE | \
NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES)
#define NTFRSAPI_BUR_FLAGS_SUPPORTED_BACKUP \
(NTFRSAPI_BUR_FLAGS_NORMAL | \
NTFRSAPI_BUR_FLAGS_BACKUP)
DWORD
WINAPI
NtFrsApiInitializeBackupRestore(
IN DWORD ErrorCallBack(IN PWCHAR, IN ULONG), OPTIONAL
IN DWORD BurFlags,
OUT PVOID *BurContext
);
/*++
Routine Description:
Called once in the lifetime of a backup/restore process. Must be
matched with a subsequent call to NtFrsApiDestroyBackupRestore().
Prepare the system for the backup or restore specified by BurFlags.
Currently, the following combinations are supported:
ASR - Automated System Recovery
NTFRSAPI_BUR_FLAGS_RESTORE |
NTFRSAPI_BUR_FLAGS_SYSTEM |
NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES |
NTFRSAPI_BUR_FLAGS_PRIMARY or NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE
DSR - Distributed Services Restore (all sets)
NTFRSAPI_BUR_FLAGS_RESTORE |
NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY |
NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES |
NTFRSAPI_BUR_FLAGS_PRIMARY or NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE
DSR - Distributed Services Restore (just the sysvol)
NTFRSAPI_BUR_FLAGS_RESTORE |
NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY
(may be followed by subsequent calls to NtFrsApiRestoringDirectory())
Normal Restore - System is up and running; just restoring files
NTFRSAPI_BUR_FLAGS_RESTORE |
NTFRSAPI_BUR_FLAGS_NORMAL |
NTFRSAPI_BUR_FLAGS_ALL_DIRECTORIES_AND_VOLUMES |
NTFRSAPI_BUR_FLAGS_AUTHORITATIVE
Normal Backup
NTFRSAPI_BUR_FLAGS_BACKUP |
NTFRSAPI_BUR_FLAGS_NORMAL
Arguments:
ErrorCallBack - Ignored if NULL.
Address of function provided by the caller. If
not NULL, this function calls back with a formatted
error message and the error code that caused the
error.
BurFlags - See above for the supported combinations
BurContext - Opaque context for this process
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApiDestroyBackupRestore(
IN PVOID *BurContext,
IN DWORD BurFlags,
OUT HKEY *HKey,
IN OUT DWORD *KeyPathSizeInBytes,
OUT PWCHAR KeyPath
);
/*++
Routine Description:
Called once in the lifetime of a backup/restore process. Must be
matched with a previous call to NtFrsApiInitializeBackupRestore().
If NtFrsApiInitializeBackupRestore() was called with:
NTFRSAPI_BUR_FLAGS_RESTORE |
NTFRSAPI_BUR_FLAGS_SYSTEM or NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY
then BurFlags may be set to one of:
NTFRSAPI_BUR_FLAGS_NONE - Do not restart the service. The key
specified by (HKey, KeyPath) must be moved into the final
registry.
NTFRSAPI_BUR_FLAGS_RESTART - Restart the service. HKey,
KeyPathSizeInBytes, and KeyPath must be NULL.
If NtFrsApiInitializeBackupRestore() was not called the above flags,
then BurFlags must be NTFRSAPI_BUR_FLAGS_NONE and HKey, KeyPathSizeInBytes,
and KeyPath must be NULL.
Arguments:
BurContext - Returned by previous call to
NtFrsApiInitializeBackupRestore().
BurFlags - Backup/Restore Flags. See Routine Description.
HKey - Address of a HKEY for that will be set to
HKEY_LOCAL_MACHINE, ...
NULL if BurContext is not for a System or
Active Directory restore or Restart is set.
KeyPathSizeInBytes - Address of of a DWORD specifying the size of
KeyPath. Set to the actual number of bytes
needed by KeyPath. ERROR_INSUFFICIENT_BUFFER
is returned if the size of KeyPath is too small.
NULL if BurContext is not for a System or
Active Directory restore or Restart is set.
KeyPath - Buffer to receive the path of the registry key.
NULL if BurContext is not for a System or
Active Directory restore or Restart is set.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApiGetBackupRestoreSets(
IN PVOID BurContext
);
/*++
Routine Description:
Cannot be called if BurContext is for a System restore.
Retrieves information about the current replicated directories
(AKA replica sets).
Arguments:
BurContext - From NtFrsApiInitializeBackupRestore()
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApiEnumBackupRestoreSets(
IN PVOID BurContext,
IN DWORD BurSetIndex,
OUT PVOID *BurSet
);
/*++
Routine Description:
Returns ERROR_NO_MORE_ITEMS if BurSetIndex exceeds the number of
sets returned by NtFrsApiGetBackupRestoreSets().
Arguments:
BurContext - From NtFrsApiInitializeBackupRestore()
BurSetIndex - Index of set. Starts at 0.
BurSet - Opaque struct representing a replicating directory.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApiIsBackupRestoreSetASysvol(
IN PVOID BurContext,
IN PVOID BurSet,
OUT BOOL *IsSysvol
);
/*++
Routine Description:
Does the specified BurSet represent a replicating SYSVOL share?
Arguments:
BurContext - From NtFrsApiInitializeBackupRestore()
BurSet - Opaque struct representing a replicating directory.
Returned by NtFrsApiEnumBackupRestoreSets(). Not
valid across calls to NtFrsApiGetBackupRestoreSets().
IsSysvol - TRUE : set is a system volume (AKA SYSVOL).
FALSE: set is a not a system volume (AKA SYSVOL).
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApiGetBackupRestoreSetDirectory(
IN PVOID BurContext,
IN PVOID BurSet,
IN OUT DWORD *DirectoryPathSizeInBytes,
OUT PWCHAR DirectoryPath
);
/*++
Routine Description:
Return the path of the replicating directory represented by BurSet.
Arguments:
BurContext - From NtFrsApiInitializeBackupRestore()
BurSet - Opaque struct representing a replicating directory.
Returned by NtFrsApiEnumBackupRestoreSets(). Not
valid across calls to NtFrsApiGetBackupRestoreSets().
DirectoryPathSizeInBytes - Address of DWORD giving size of
DirectoryPath. Cannot be NULL.
Set to the number of bytes needed
to return DirectoryPath.
ERROR_INSUFFICIENT_BUFFER is returned if
DirectoryPath is too small.
DirectoryPath - Buffer that is *DirectoryPathSizeInBytes
bytes in length. Contains path of replicating
directory.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApiGetBackupRestoreSetPaths(
IN PVOID BurContext,
IN PVOID BurSet,
IN OUT DWORD *PathsSizeInBytes,
OUT PWCHAR Paths,
IN OUT DWORD *FiltersSizeInBytes,
OUT PWCHAR Filters
);
/*++
Routine Description:
Return a multistring that contains the paths to other files
and directories needed for proper operation of the replicated
directory represented by BurSet. Return another multistring
that details the backup filters to be applied to the paths
returned by this function and the path returned by
NtFrsApiGetBackupRestoreSetDirectory().
The paths may overlap the replicated directory.
The paths may contain nested entries.
Filters is a multistring in the same format as the values for
the registry key FilesNotToBackup.
The replicated directory can be found with
NtFrsApiGetBackupRestoreSetDirectory(). The replicated directory
may overlap one or more entries in Paths.
ERROR_PATH_NOT_FOUND is returned if the paths could not be
determined.
Arguments:
BurContext - From NtFrsApiInitializeBackupRestore()
BurSet - Opaque struct representing a replicating directory.
Returned by NtFrsApiEnumBackupRestoreSets(). Not
valid across calls to NtFrsApiGetBackupRestoreSets().
PathsSizeInBytes - Address of DWORD giving size of Paths.
Cannot be NULL. Set to the number of bytes
needed to return Paths.
ERROR_INSUFFICIENT_BUFFER is returned if
Paths is too small.
Paths - Buffer that is *PathsSizeInBytes
bytes in length. Contains the paths of the
other files and directories needed for proper
operation of the replicated directory.
FiltersSizeInBytes - Address of DWORD giving size of Filters.
Cannot be NULL. Set to the number of bytes
needed to return Filters.
ERROR_INSUFFICIENT_BUFFER is returned if
Filters is too small.
Filters - Buffer that is *FiltersSizeInBytes bytes in
length. Contains the backup filters to be
applied to Paths, the contents of directories
in Paths, and the replicated directory.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApiRestoringDirectory(
IN PVOID BurContext,
IN PVOID BurSet,
IN DWORD BurFlags
);
/*++
Routine Description:
The backup/restore application is about to restore the directory
specified by BurSet (See NtFrsApiEnumBackupRestoreSets()). Matched
with a later call to NtFrsApiFinishedRestoringDirectory().
This call is supported only if NtFrsApiInitializeBackupRestore()
were called with the flags:
NTFRSAPI_BUR_FLAGS_RESTORE |
NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY
BurFlags can be NTFRSAPI_BUR_FLAGS_PRIMARY or
NTFRSAPI_BUR_FLAGS_NON_AUTHORITATIVE and overrides any value
specified in the call to NtFrsApiInitializeBackupRestore().
Arguments:
BurContext - Opaque context from NtFrsApiInitializeBackupRestore()
BurSet - Opaque set from NtFrsApiEnumBackupRestoreSets();
BurFlags - See above for the supported combinations
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApiFinishedRestoringDirectory(
IN PVOID BurContext,
IN PVOID BurSet,
IN DWORD BurFlags
);
/*++
Routine Description:
Finished restoring directory for BurSet. Matched by a previous call
to NtFrsApiRestoringDirectory().
This call is supported only if NtFrsApiInitializeBackupRestore()
were called with the flags:
NTFRSAPI_BUR_FLAGS_RESTORE |
NTFRSAPI_BUR_FLAGS_ACTIVE_DIRECTORY
BurFlags must be NTFRSAPI_BUR_FLAGS_NONE.
Arguments:
BurContext - Opaque context from NtFrsApiInitializeBackupRestore()
BurSet - Opaque set from NtFrsApiEnumBackupRestoreSets();
BurFlags - See above for the supported combinations
Return Value:
Win32 Status
--*/
#define NTFRSAPI_MAX_INTERVAL ((((ULONG)0x7FFFFFFF) / 1000) / 60)
#define NTFRSAPI_MIN_INTERVAL (1)
#define NTFRSAPI_DEFAULT_LONG_INTERVAL (1 * 60) // 1 hour
#define NTFRSAPI_DEFAULT_SHORT_INTERVAL (5) // 5 minutes
DWORD
WINAPI
NtFrsApi_Set_DsPollingIntervalW(
IN PWCHAR ComputerName, OPTIONAL
IN ULONG UseShortInterval,
IN ULONG LongInterval,
IN ULONG ShortInterval
);
/*++
Routine Description:
The NtFrs service polls the DS occasionally for configuration changes.
This API alters the polling interval and, if the service is not
in the middle of a polling cycle, forces the service to begin a
polling cycle.
The service uses the long interval by default. The short interval
is used after the ds configuration has been successfully
retrieved and the service is now verifying that the configuration
is not in flux. This API can be used to force the service to use
the short interval until a stable configuration has been retrieved.
After which, the service reverts back to the long interval.
The default values for ShortInterval and LongInterval can be
changed by setting the parameters to a non-zero value. If zero,
the current values remain unchanged and a polling cycle is initiated.
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.
UseShortInterval - If non-zero, the service switches to the short
interval until a stable configuration is retrieved
from the DS or another call to this API is made.
Otherwise, the service uses the long interval.
LongInterval - Minutes between polls of the DS. The value must fall
between NTFRSAPI_MIN_INTERVAL and NTFRSAPI_MAX_INTERVAL,
inclusive. If 0, the interval is unchanged.
ShortInterval - Minutes between polls of the DS. The value must fall
between NTFRSAPI_MIN_INTERVAL and NTFRSAPI_MAX_INTERVAL,
inclusive. If 0, the interval is unchanged.
Return Value:
Win32 Status
--*/
DWORD
WINAPI
NtFrsApi_Get_DsPollingIntervalW(
IN PWCHAR ComputerName, OPTIONAL
OUT ULONG *Interval,
OUT ULONG *LongInterval,
OUT ULONG *ShortInterval
);
/*++
Routine Description:
The NtFrs service polls the DS occasionally for configuration changes.
This API returns the values the service uses for polling intervals.
The service uses the long interval by default. The short interval
is used after the ds configuration has been successfully
retrieved and the service is now verifying that the configuration
is not in flux. The short interval is also used if the
NtFrsApi_Set_DsPollingIntervalW() is used to force usage of the short
interval until a stable configuration has been retrieved. After which,
the service reverts back to the long interval.
The value returned in Interval is the polling interval currently in
use.
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.
Interval - The current polling interval in minutes.
LongInterval - The long interval in minutes.
ShortInterval - The short interval in minutes.
Return Value:
Win32 Status
--*/
#ifdef __cplusplus
}
#endif
#endif _FRSAPIP_H_
Reference in a new issue Copy permalink