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

729 lines
22 KiB
C
Raw Permalink Normal View History

Add source files
2020-09-26 03:20:57 -05:00
/*++ BUILD Version: 0001 // Increment this if a change has global effects
Copyright (c) 1997-1999 Microsoft Corporation
Module Name:
ntdsbcli.h
Abstract:
This header contains the interface definition for the NT Directory Service
Backup Client APIs.
Environment:
User Mode - Win32
Notes:
--*/
#ifndef _NTDSBCLI_H_
#define _NTDSBCLI_H_
#if _MSC_VER > 1000
#pragma once
#endif
#ifdef __cplusplus
extern "C" {
#endif
#ifdef MIDL_PASS
#define xRPC_STRING [string]
#else
#define xRPC_STRING
#if !defined(_NATIVE_WCHAR_T_DEFINED)
typedef unsigned short WCHAR;
#else
typedef wchar_t WCHAR;
#endif
#endif
#ifndef _NTDSBCLI_DEFINED
#define NTDSBCLI_API __declspec(dllimport) _stdcall
#else
#define NTDSBCLI_API
#endif
// HRESULT should be defined if the user included ntdef.h or winnt.h or wtypes.h
// Define it anyways just in case it is not defined yet
#ifndef _HRESULT_DEFINED
#define _HRESULT_DEFINED
typedef LONG HRESULT;
#endif // _HRESULT_DEFINED
#define g_wszBackupAnnotation L"NTDS Backup Interface"
#define g_aszBackupAnnotation "NTDS Backup Interface"
#define g_wszRestoreAnnotation L"NTDS Restore Interface"
#define g_aszRestoreAnnotation "NTDS Restore Interface"
#ifdef UNICODE
#define g_szBackupAnnotation g_wszBackupAnnotation
#define g_szRestoreAnnotation g_wszRestoreAnnotation
#else
#define g_szBackupAnnotation g_aszBackupAnnotation
#define g_szRestoreAnnotation g_aszRestoreAnnotation
#endif // UNICODE
// Type of Backup passed to DsBackupPrepare()
// BACKUP_TYPE_FULL: Requesting backup of the complete DS (DIT, Log files, and Patch files)
// BACKUP_TYPE_LOGS_ONLY: Requesting backup of only the log files
// BACKUP_TYPE_INCREMENTAL: Requesting incremental backup i.e. backing up only changes that happened since last backup
#define BACKUP_TYPE_FULL 0x01
#define BACKUP_TYPE_LOGS_ONLY 0x02
#define BACKUP_TYPE_INCREMENTAL 0x04 // not supported in product1
// Type of Restore passed to DsRestorePrepare()
// RESTORE_TYPE_AUTHORATATIVE: The restored version wins throughout the enterprise
// RESTORE_TYPE_ONLINE: Restoration is done when NTDS is online.
// RESTORE_TYPE_CATCHUP: The restored version is reconciled through the standard reconciliation logic so that the
// restored DIT can catchup with the rest of the enterprise.
#define RESTORE_TYPE_AUTHORATATIVE 0x01
#define RESTORE_TYPE_ONLINE 0x02 // not supported in product1
#define RESTORE_TYPE_CATCHUP 0x04 // this is the default restore mode
// Setting the current log # to this value would disable incremental/differential backup
#define BACKUP_DISABLE_INCREMENTAL 0xffffffff
// BFT is the bit flag used to represent file types (directory/dit/logfile/etc.)
// We keep them as a character so that we can append/prepend them to the actual file
// path. The code in the Backup API's rely on the fact that values 0-256 in 8 bit ascii
// map to the values 0-256 in unicode.
#ifdef UNICODE
typedef WCHAR BFT;
#else
typedef CHAR BFT;
#endif
// Bit flags:
// BFT_DIRECTORY - indicates path specified is a directory
// BFT_DATABASE_DIRECTORY - indicates that file goes into database directory
// BFT_LOG_DIRECTORY - indicates that the file goes into log directory
#define BFT_DIRECTORY 0x80
#define BFT_DATABASE_DIRECTORY 0x40
#define BFT_LOG_DIRECTORY 0x20
// Following combinations are defined for easy use of the filetype and the directory into
// into which it goes
#define BFT_LOG (BFT)(TEXT('\x01') | BFT_LOG_DIRECTORY)
#define BFT_LOG_DIR (BFT)(TEXT('\x02') | BFT_DIRECTORY)
#define BFT_CHECKPOINT_DIR (BFT)(TEXT('\x03') | BFT_DIRECTORY)
#define BFT_NTDS_DATABASE (BFT)(TEXT('\x04') | BFT_DATABASE_DIRECTORY)
#define BFT_PATCH_FILE (BFT)(TEXT('\x05') | BFT_LOG_DIRECTORY)
#define BFT_UNKNOWN (BFT)(TEXT('\x0f'))
#include <ntdsbmsg.h>
// Backup Context Handle
typedef void *HBC;
typedef struct tagEDB_RSTMAPA
{
xRPC_STRING char *szDatabaseName;
xRPC_STRING char *szNewDatabaseName;
} EDB_RSTMAPA, *PEDB_RSTMAPA; /* restore map */
// required for NTDS unicode support.
// UNDONE: NYI
#define UNICODE_RSTMAP
typedef struct tagEDB_RSTMAPW {
xRPC_STRING WCHAR *wszDatabaseName;
xRPC_STRING WCHAR *wszNewDatabaseName;
} EDB_RSTMAPW, *PEDB_RSTMAPW;
#ifdef UNICODE
#define EDB_RSTMAP EDB_RSTMAPW
#define PEDB_RSTMAP PEDB_RSTMAPW
#else
#define EDB_RSTMAP EDB_RSTMAPA
#define PEDB_RSTMAP PEDB_RSTMAPA
#endif
// For all the functions in this interface that have atleast one string
// parameter provide macros to invoke the appropriate version of the
// corresponding function.
#ifdef UNICODE
#define DsIsNTDSOnline DsIsNTDSOnlineW
#define DsBackupPrepare DsBackupPrepareW
#define DsBackupGetDatabaseNames DsBackupGetDatabaseNamesW
#define DsBackupOpenFile DsBackupOpenFileW
#define DsBackupGetBackupLogs DsBackupGetBackupLogsW
#define DsRestoreGetDatabaseLocations DsRestoreGetDatabaseLocationsW
#define DsRestorePrepare DsRestorePrepareW
#define DsRestoreRegister DsRestoreRegisterW
#define DsSetCurrentBackupLog DsSetCurrentBackupLogW
#define DsSetAuthIdentity DsSetAuthIdentityW
#else
#define DsIsNTDSOnline DsIsNTDSOnlineA
#define DsBackupPrepare DsBackupPrepareA
#define DsBackupGetDatabaseNames DsBackupGetDatabaseNamesA
#define DsBackupOpenFile DsBackupOpenFileA
#define DsBackupGetBackupLogs DsBackupGetBackupLogsA
#define DsRestoreGetDatabaseLocations DsRestoreGetDatabaseLocationsA
#define DsRestorePrepare DsRestorePrepareA
#define DsRestoreRegister DsRestoreRegisterA
#define DsSetCurrentBackupLog DsSetCurrentBackupLogA
#define DsSetAuthIdentity DsSetAuthIdentityA
#endif // #ifdef UNICODE
/*************************************************************************************
Routine Description:
DsIsNTDSOnline
Checks to see if the NTDS is Online on the given server. This call is
guaranteed to return quickly.
Arguments:
[in] szServerName - UNC name of the server to check
[out] pfNTDSOnline - pointer to receive the bool result (TRUE if NTDS is
online; FALSE, otherwise)
Return Value:
ERROR_SUCCESS if the call executed successfully;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsIsNTDSOnlineA(
LPCSTR szServerName,
BOOL *pfNTDSOnline
);
HRESULT
NTDSBCLI_API
DsIsNTDSOnlineW(
LPCWSTR szServerName,
BOOL *pfNTDSOnline
);
/*************************************************************************************
Routine Description:
DsBackupPrepare
Prepares the DS for the online backup and returns a Backup Context Handle
which should be used in the subsequent calls to other backup functions.
Arguments:
[in] szBackupServer - UNC name of the server to be prepared for online backup
[in] grbit - flag to be passed to jet while backing up dbs
[in] btFlag - BACKUP_TYPE_FULL or BACKUP_TYPE_LOGS_ONLY
[out] ppvExpiryToken - pointer that will receive the pointer to the
Expiry Token associated with this backup; Client should save
this token and send it back through DsRestorePrepare() when
attempting a restore; allocated memory should be freed using
DsBackupFree() API by the caller when it is no longer needed.
[out] pcbExpiryTokenSize - pointer to receive the size of the expiry token
returned.
[out] phbc - pointer that will receive the backup context handle
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsBackupPrepareA(
LPCSTR szBackupServer,
ULONG grbit,
ULONG btFlag,
PVOID *ppvExpiryToken,
LPDWORD pcbExpiryTokenSize,
HBC *phbc
);
HRESULT
NTDSBCLI_API
DsBackupPrepareW(
LPCWSTR szBackupServer,
ULONG grbit,
ULONG btFlag,
PVOID *ppvExpiryToken,
LPDWORD pcbExpiryTokenSize,
HBC *phbc
);
/*************************************************************************************
Routine Description:
DsBackupGetDatabaseNames
Gives the list of data bases that need to be backed up for the given
backup context
Arguments:
[in] hbc - backup context handle
[out] pszAttachmentInfo - pointer that will receive the pointer to the attachment
info; allocated memory should be freed using DsBackupFree() API by the
caller when it is no longer needed; Attachment info is an array of
null-terminated filenames and and the list is terminated by two-nulls.
[out] pcbSize - will receive the number of bytes returned
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsBackupGetDatabaseNamesA(
HBC hbc,
LPSTR *pszAttachmentInfo,
LPDWORD pcbSize
);
HRESULT
NTDSBCLI_API
DsBackupGetDatabaseNamesW(
HBC hbc,
LPWSTR *pszAttachmentInfo,
LPDWORD pcbSize
);
/*************************************************************************************
Routine Description:
DsBackupOpenFile
Opens the given attachment for read.
Arguments:
[in] hbc - backup context handle
[in] szAttachmentName - name of the attachment to be opened for read
[in] cbReadHintSize - suggested size in bytes that might be used during the
subsequent reads on this attachement
[out] pliFileSize - pointer to a large integer that would receive the size in
bytes of the given attachment
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsBackupOpenFileA(
HBC hbc,
LPCSTR szAttachmentName,
DWORD cbReadHintSize,
LARGE_INTEGER *pliFileSize
);
HRESULT
NTDSBCLI_API
DsBackupOpenFileW(
HBC hbc,
LPCWSTR szAttachmentName,
DWORD cbReadHintSize,
LARGE_INTEGER *pliFileSize
);
/*************************************************************************************
Routine Description:
DsBackupRead
Reads the currently open attachment bytes into the given buffer. The client
application is expected to call this function repeatedly until it gets the
entire file (the application would have received the file size through the
DsBackupOpenFile() call before.
Arguments:
[in] hbc - backup context handle
[in] pvBuffer - pointer to the buffer that would receive the read data.
[in] cbBuffer - specifies the size of the above buffer
[out] pcbRead - pointer to receive the actual number of bytes read.
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsBackupRead(
HBC hbc,
PVOID pvBuffer,
DWORD cbBuffer,
PDWORD pcbRead
);
/*************************************************************************************
Routine Description:
DsBackupClose
To be called by the application after it completes reading all the data in
the currently opened attachement.
Arguments:
[in] hbc - backup context handle
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsBackupClose(
HBC hbc
);
/*************************************************************************************
Routine Description:
DsBackupGetBackupLogs
Gives the list of log files that need to be backed up for the given
backup context
Arguments:
[in] hbc - backup context handle
[out] pszBackupLogFiles - pointer that will receive the pointer to the list of
log files; allocated memory should be freed using DsBackupFree() API by the
caller when it is no longer needed; Log files are returned in an array of
null-terminated filenames and and the list is terminated by two-nulls.
[out] pcbSize - will receive the number of bytes returned
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsBackupGetBackupLogsA(
HBC hbc,
LPSTR *pszBackupLogFiles,
LPDWORD pcbSize
);
HRESULT
NTDSBCLI_API
DsBackupGetBackupLogsW(
HBC hbc,
LPWSTR *pszBackupLogFiles,
LPDWORD pcbSize
);
/*************************************************************************************
Routine Description:
DsBackupTruncateLogs
Called to truncate the already read backup logs.
Arguments:
[in] hbc - backup context handle
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsBackupTruncateLogs(
HBC hbc
);
/*************************************************************************************
Routine Description:
DsBackupEnd
Called to end the current backup session.
Arguments:
[in] hbc - backup context handle of the backup session
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsBackupEnd(
HBC hbc
);
/*************************************************************************************
Routine Description:
DsBackupFree
Should be used by the application to free any buffer allocated by the
NTDSBCLI dll.
Arguments:
[in] pvBuffer - pointer to the buffer that is to be freed.
Return Value:
None.
**************************************************************************************/
VOID
NTDSBCLI_API
DsBackupFree(
PVOID pvBuffer
);
/*************************************************************************************
Routine Description:
DsRestoreGetDatabaseLocations
Called both at backup time as well at restoration time to get the data base
locations for different types of files.
Arguments:
[in] hbc - backup context handle which would have been obtained through
DsBackupPrepare() in the backup case and through DsRestorePrepare()
in the restore case.
[out] pszDatabaseLocationList - pointer that will receive the pointer to the list of
database locations; allocated memory should be freed using DsBackupFree() API by the
caller when it is no longer needed; locations are returned in an array of
null-terminated names and and the list is terminated by two-nulls.
The first character of each name is the BFT character that indicates the type
of the file and the rest of the name tells gives the path into which that
particular type of file should be restored.
[out] pcbSize - will receive the number of bytes returned
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsRestoreGetDatabaseLocationsA(
HBC hbc,
LPSTR *pszDatabaseLocationList,
LPDWORD pcbSize
);
HRESULT
NTDSBCLI_API
DsRestoreGetDatabaseLocationsW(
HBC hbc,
LPWSTR *pszDatabaseLocationList,
LPDWORD pcbSize
);
/*************************************************************************************
Routine Description:
DsRestorePrepare
Called to indicate beginning of a restore session.
Arguments:
[in] szServerName - UNC name of the server into which the restore operation is
going to be performed.
[in] rtFlag - Or'ed combination of RESTORE_TYPE_* flags; 0 if no special flags
are to be specified
[in] pvExpiryToken - pointer to the expiry token associated with this
backup. The client would have received this when they backed up the DS.
[in] cbExpiryTokenSize - size of the expiry token.
[out] phbc - pointer to receive the backup context handle which is to be passed
to the subsequent restore APIs
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsRestorePrepareA(
LPCSTR szServerName,
ULONG rtFlag,
PVOID pvExpiryToken,
DWORD cbExpiryTokenSize,
HBC *phbc
);
HRESULT
NTDSBCLI_API
DsRestorePrepareW(
LPCWSTR szServerName,
ULONG rtFlag,
PVOID pvExpiryToken,
DWORD cbExpiryTokenSize,
HBC *phbc
);
/*************************************************************************************
Routine Description:
DsRestoreRegister
This will register a restore operation. It will interlock all sbsequent restore
operations, and will prevent the restore target from starting until the call
to DsRestoreRegisterComplete() is made.
Arguments:
[in] hbc - backup context handle for the restore session.
[in] szCheckPointFilePath - path where the check point files are restored
[in] szLogPath - path where the log files are restored
[in] rgrstmap - restore map
[in] crstmap - tells if ther is a new restore map
[in] szBackupLogPath - path where the backup logs are located
[in] genLow - Lowest log# that was restored in this restore session
[in] genHigh - Highest log# that was restored in this restore session
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsRestoreRegisterA(
HBC hbc,
LPCSTR szCheckPointFilePath,
LPCSTR szLogPath,
EDB_RSTMAPA rgrstmap[],
LONG crstmap,
LPCSTR szBackupLogPath,
ULONG genLow,
ULONG genHigh
);
HRESULT
NTDSBCLI_API
DsRestoreRegisterW(
HBC hbc,
LPCWSTR szCheckPointFilePath,
LPCWSTR szLogPath,
EDB_RSTMAPW rgrstmap[],
LONG crstmap,
LPCWSTR szBackupLogPath,
ULONG genLow,
ULONG genHigh
);
/*************************************************************************************
Routine Description:
DsRestoreRegisterComplete
Called to indicate that a previously registered restore is complete.
Arguments:
[in] hbc - backup context handle
[in] hrRestoreState - success code if the restore was successful
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsRestoreRegisterComplete(
HBC hbc,
HRESULT hrRestoreState
);
/*************************************************************************************
Routine Description:
DsRestoreEnd
Called to end a restore session
Arguments:
[in] hbc - backup context handle
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsRestoreEnd(
HBC hbc
);
/*************************************************************************************
Routine Description:
DsSetCurrentBackupLog
Called to set the current backup log number after a successful restore
Arguments:
[in] szServerName - UNC name of the server for which the current backup log has
to be set
[in] dwCurrentLog - current log number
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsSetCurrentBackupLogA(
LPCSTR szServerName,
DWORD dwCurrentLog
);
HRESULT
NTDSBCLI_API
DsSetCurrentBackupLogW(
LPCWSTR szServerName,
DWORD dwCurrentLog
);
/*************************************************************************************
Routine Description:
DsSetAuthIdentity
Used to set the security context under which the client APIs are to be
called. If this function is not called, security context of the current
process is assumed.
Arguments:
[in] szUserName - name of the user
[in] szDomainName - name of the domain the user belongs to
[in] szPassword - password of the user in the specified domain
Return Value:
One of the standard HRESULT success codes;
Failure code otherwise.
**************************************************************************************/
HRESULT
NTDSBCLI_API
DsSetAuthIdentityA(
LPCSTR szUserName,
LPCSTR szDomainName,
LPCSTR szPassword
);
HRESULT
NTDSBCLI_API
DsSetAuthIdentityW(
LPCWSTR szUserName,
LPCWSTR szDomainName,
LPCWSTR szPassword
);
#ifdef __cplusplus
}
#endif
#endif // _NTDSBCLI_H_
Reference in a new issue Copy permalink