' ########################################################################################
' Microsoft Windows
' File: CertBCli.inc
' Contents: Cert Server backup client APIs
' Copyright (c) 2011 Jos? Roca
' Portions Copyright (c) Microsoft Corporation.
' All Rights Reserved.
' THIS CODE AND INFORMATION IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
' EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF
' MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
' ########################################################################################
#IF NOT %DEF(PBX_CertBCli_PBI)
#DEFINE PBX_CertBCli_PBI
%EQUATE `CERTBCLI_INC = 1
'#define szBACKUPANNOTATION "Cert Server Backup Interface"
'#define wszBACKUPANNOTATION TEXT(szBACKUPANNOTATION)
$szBACKUPANNOTATION = "Cert Server Backup Interface"
$$wszBACKUPANNOTATION = "Cert Server Backup Interface"$$
'#define szRESTOREANNOTATION "Cert Server Restore Interface"
'#define wszRESTOREANNOTATION TEXT(szRESTOREANNOTATION)
$szRESTOREANNOTATION = "Cert Server Restore Interface"
$$wszRESTOREANNOTATION = "Cert Server Restore Interface"$$
'// Type of Backup passed to CertSrvBackupPrepare:
'// CSBACKUP_TYPE_FULL: Requesting backup of the complete DB (DB & Log files)
'// CSBACKUP_TYPE_LOGS_ONLY: Requesting backup of only the log files
'// CSBACKUP_TYPE_INCREMENTAL: Requesting incremental backup
'// CertSrvBackupPrepare flags:
%EQUATE `CSBACKUP_TYPE_FULL = &H00000001
%EQUATE `CSBACKUP_TYPE_LOGS_ONLY = &H00000002
'//#define CSBACKUP_TYPE_INCREMENTAL 0x00000004 // not yet supported
%EQUATE `CSBACKUP_TYPE_MASK = &H00000003 ' // valid flags
'// Type of Restore passed to CertSrvRestorePrepare:
'// CSRESTORE_TYPE_FULL: Requesting restore of the complete DB (DB & Log files)
'// CSRESTORE_TYPE_ONLINE: Restoration is done when Cert Server is online.
%EQUATE `CSRESTORE_TYPE_FULL = &H00000001 ' // else incremental
%EQUATE `CSRESTORE_TYPE_ONLINE = &H00000002 ' // not yet supported
%EQUATE `CSRESTORE_TYPE_CATCHUP = &H00000004 ' // not yet supported
%EQUATE `CSRESTORE_TYPE_MASK = &H00000005 ' // valid flags
'// Setting the current log # to this value would disable incremental backup
%EQUATE `CSBACKUP_DISABLE_INCREMENTAL = &Hffffffff
'// 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.
'typedef WCHAR CSBFT;
'// Bit flags:
'// CSBFT_DIRECTORY - path specified is a directory
'// CSBFT_DATABASE_DIRECTORY - that file goes into database directory
'// CSBFT_LOG_DIRECTORY - that the file goes into log directory
%EQUATE `CSBFT_DIRECTORY = &H80
%EQUATE `CSBFT_DATABASE_DIRECTORY = &H40
%EQUATE `CSBFT_LOG_DIRECTORY = &H20
'// Following combinations are defined for easy use of the filetype and the
'// directory into into which it goes
'#define CSBFT_LOG ((CSBFT) (TEXT('\x01') | CSBFT_LOG_DIRECTORY))
'#define CSBFT_LOG_DIR ((CSBFT) (TEXT('\x02') | CSBFT_DIRECTORY))
'#define CSBFT_CHECKPOINT_DIR ((CSBFT) (TEXT('\x03') | CSBFT_DIRECTORY))
'#define CSBFT_CERTSERVER_DATABASE ((CSBFT) (TEXT('\x04') | CSBFT_DATABASE_DIRECTORY))
'#define CSBFT_PATCH_FILE ((CSBFT) (TEXT('\x05') | CSBFT_LOG_DIRECTORY))
'#define CSBFT_UNKNOWN ((CSBFT) (TEXT('\x0f')))
'// Backup Context Handle
'typedef void *HCSBC;
#IF NOT %DEF(%CSEDB_RSTMAP)
%EQUATE `CSEDB_RSTMAP = 1
' // Size = 8 bytes
TYPE CSEDB_RSTMAPW DWORD
 pwszDatabaseName AS WSTRINGZ PTR ' RPC_STRING WCHAR *
 pwszNewDatabaseName AS WSTRINGZ PTR ' RPC_STRING WCHAR *
END TYPE
MACRO CSEDB_RSTMAP = CSEDB_RSTMAPW
#ENDIF ' // CSEDB_RSTMAP
'//+--------------------------------------------------------------------------
'// CertSrvIsServerOnline -- check to see if the Cert Server is Online on the
'// given server. This call is guaranteed to return quickly.
'//
'// Parameters:
'// [in] pwszServerName - name or config string of the server to check
'// [out] pfServerOnline - pointer to receive the bool result
'// (TRUE if Cert Server is online; FALSE, otherwise)
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//+--------------------------------------------------------------------------
' There is not an ansi version
DECLARE FUNCTION CertSrvIsServerOnlineW LIB "certadm.dll" ALIAS "CertSrvIsServerOnlineW" ( BYREF pwszServerName AS WSTRINGZ , BYREF pfServerOnline AS LONG ) AS LONG
MACRO CertSrvIsServerOnline = CertSrvIsServerOnlineW
'//+--------------------------------------------------------------------------
'// CertSrvBackupGetDynamicFileList -- return the list of dynamic files that
'// need to be backed up in addition to database files.
'//
'// Parameters:
'// [in] hbc - backup context handle
'// [out] ppwszzFileList - pointer to receive the pointer to the file list;
'// allocated memory should be freed using CertSrvBackupFree() API
'// by the caller when it is no longer needed; The file list info
'// is an array of null-terminated filenames and the list is
'// terminated by two L'\0's.
'// [out] pcbSize - will receive the number of bytes returned
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
' There is not an ansi version
DECLARE FUNCTION CertSrvBackupGetDynamicFileListW LIB "certadm.dll" ALIAS "CertSrvBackupGetDynamicFileListW" ( BYVAL hbc AS QUAD , BYREF ppwszzFileList AS QUAD , BYREF pcbSize AS QUAD ) AS LONG
MACRO CertSrvBackupGetDynamicFileList = CertSrvBackupGetDynamicFileListW
'//+--------------------------------------------------------------------------
'// CertSrvBackupPrepare -- prepare the DB for the online backup and return a
'// Backup Context Handle to be used for subsequent calls to backup
'// functions.
'//
'// Parameters:
'// [in] pwszServerName - name or config string of the server to check
'// [in] grbitJet - flag to be passed to jet while backing up dbs
'// [in] dwBackupFlags - CSBACKUP_TYPE_FULL or CSBACKUP_TYPE_LOGS_ONLY
'// [out] phbc - pointer that will receive the backup context handle
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
' There is not an ansi version
DECLARE FUNCTION CertSrvBackupPrepareW LIB "certadm.dll" ALIAS "CertSrvBackupPrepareW" ( BYREF pwszServerName AS WSTRINGZ , BYVAL grbitJet AS QUAD , BYVAL dwBackupFlags AS QUAD , BYREF phbc AS QUAD ) AS LONG
MACRO CertSrvBackupPrepare = CertSrvBackupPrepareW
'//+--------------------------------------------------------------------------
'// CertSrvBackupGetDatabaseNames -- return the list of data bases that need to
'// be backed up for the given backup context
'//
'// Parameters:
'// [in] hbc - backup context handle
'// [out] ppwszzAttachmentInformation - pointer to receive the pointer to
'// the attachment info; allocated memory should be freed using
'// CertSrvBackupFree() API by the caller when it is no longer
'// needed; Attachment info is an array of null-terminated
'// filenames and the list is terminated by two L'\0's.
'// [out] pcbSize - will receive the number of bytes returned
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
' There is not an ansi version
DECLARE FUNCTION CertSrvBackupGetDatabaseNamesW LIB "certadm.dll" ALIAS "CertSrvBackupGetDatabaseNamesW" ( BYVAL hbc AS QUAD , BYREF ppwszzAttachmentInformation AS QUAD , BYREF pcbSize AS QUAD ) AS LONG
MACRO CertSrvBackupGetDatabaseNames = CertSrvBackupGetDatabaseNamesW
'//+--------------------------------------------------------------------------
'// CertSrvBackupOpenFile -- open the given attachment for read.
'//
'// Parameters:
'// [in] hbc - backup context handle
'// [in] pwszAttachmentName - 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 attachment
'// [out] pliFileSize - pointer to a large integer that would receive the
'// size in bytes of the given attachment
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
' There is not an ansi version
DECLARE FUNCTION CertSrvBackupOpenFileW LIB "certadm.dll" ALIAS "CertSrvBackupOpenFileW" ( BYVAL hbc AS QUAD , BYREF pwszAttachmentName AS WSTRINGZ , BYVAL cbReadHintSize AS QUAD , BYREF pliFileSize AS QUAD ) AS LONG
MACRO CertSrvBackupOpenFile = CertSrvBackupOpenFileW
'//+--------------------------------------------------------------------------
'// CertSrvBackupRead -- read 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 CertSrvBackupOpenFile call before.
'//
'// Parameters:
'// [in] hbc - backup context handle
'// [out] 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.
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
DECLARE FUNCTION CertSrvBackupRead LIB "certadm.dll" ALIAS "CertSrvBackupRead" ( BYVAL hbc AS QUAD , BYREF pvBuffer AS ANY , BYVAL cbBuffer AS QUAD , BYREF pcbRead AS QUAD ) AS LONG
'//+--------------------------------------------------------------------------
'// CertSrvBackupClose -- called by the application after it completes reading all
'// the data in the currently opened attachement.
'//
'// Parameters:
'// [in] hbc - backup context handle
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
DECLARE FUNCTION CertSrvBackupClose LIB "certadm.dll" ALIAS "CertSrvBackupClose" ( BYVAL hbc AS QUAD ) AS LONG
'//+--------------------------------------------------------------------------
'// CertSrvBackupGetBackupLogs -- return the list of log files that need to be
'// backed up for the given backup context
'//
'// Parameters:
'// [in] hbc - backup context handle
'// [out] pwszzBackupLogFiles - pointer that will receive the pointer to
'// the list of log files; allocated memory should be freed using
'// CertSrvBackupFree() API by the caller when it is no
'// longer needed; Log files are returned in an array of
'// null-terminated filenames and the list is terminated by two
'// L'\0's
'// [out] pcbSize - will receive the number of bytes returned
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
' There is not ansi version
DECLARE FUNCTION CertSrvBackupGetBackupLogsW LIB "certadm.dll" ALIAS "CertSrvBackupGetBackupLogsW" ( BYVAL hbc AS QUAD , BYREF ppwszzBackupLogFiles AS QUAD , BYREF pcbSize AS QUAD ) AS LONG
MACRO CertSrvBackupGetBackupLogs = CertSrvBackupGetBackupLogsW
'//+--------------------------------------------------------------------------
'// CertSrvBackupTruncateLogs -- called to truncate the already read backup logs.
'//
'// Parameters:
'// [in] hbc - backup context handle
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
DECLARE FUNCTION CertSrvBackupTruncateLogs LIB "certadm.dll" ALIAS "CertSrvBackupTruncateLogs" ( BYVAL hbc AS QUAD ) AS LONG
'//+--------------------------------------------------------------------------
'// CertSrvBackupEnd -- called to end the current backup session.
'//
'// Parameters:
'// [in] hbc - backup context handle of the backup session
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
DECLARE FUNCTION CertSrvBackupEnd LIB "certadm.dll" ALIAS "CertSrvBackupEnd" ( BYVAL hbc AS QUAD ) AS LONG
'//+--------------------------------------------------------------------------
'// CertSrvBackupFree -- free any buffer allocated by certbcli.dll APIs.
'//
'// Parameters:
'// [in] pv - pointer to the buffer that is to be freed.
'//
'// Returns:
'// None.
'//---------------------------------------------------------------------------
DECLARE FUNCTION CertSrvBackupFree LIB "certadm.dll" ALIAS "CertSrvBackupFree" ( BYVAL pv AS QUAD ) AS LONG
'//+--------------------------------------------------------------------------
'// CertSrvRestoreGetDatabaseLocations -- called both at backup time as well as
'// at restorate time to get data base locations for different types of
'// files.
'//
'// Parameters:
'// [in] hbc - backup context handle which would have been obtained
'// through CertSrvBackupPrepare in the backup case and through
'// CertSrvRestorePrepare in the restore case.
'// [out] ppwszzDatabaseLocationList - pointer that will receive the
'// pointer to the list of database locations; allocated memory
'// should be freed using CertSrvBackupFree() 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 L'\0's. 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
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
' There is not ansi version
DECLARE FUNCTION CertSrvRestoreGetDatabaseLocationsW LIB "certadm.dll" ALIAS "CertSrvRestoreGetDatabaseLocationsW" ( BYVAL hbc AS QUAD , BYREF ppwszzDatabaseLocationList AS QUAD , BYREF pcbSize AS QUAD ) AS LONG
MACRO CertSrvRestoreGetDatabaseLocations = CertSrvRestoreGetDatabaseLocationsW
'//+--------------------------------------------------------------------------
'// CertSrvRestorePrepare -- indicate beginning of a restore session.
'//
'// Parameters:
'// [in] pwszServerName - name or config string of the server into which
'// the restore operation is going to be performed.
'// [in] dwRestoreFlags - Or'ed combination of CSRESTORE_TYPE_* flags;
'// 0 if no special flags are to be specified
'// [out] phbc - pointer to receive the backup context handle which is to
'// be passed to the subsequent restore APIs
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
' There is not ansi version
DECLARE FUNCTION CertSrvRestorePrepareW LIB "certadm.dll" ALIAS "CertSrvRestorePrepareW" ( BYREF pwszServerName AS WSTRINGZ , BYVAL dwRestoreFlags AS QUAD , BYREF phbc AS QUAD ) AS LONG
MACRO CertSrvRestorePrepare = CertSrvRestorePrepareW
'//+--------------------------------------------------------------------------
'// CertSrvRestoreRegister -- register a restore operation. It will interlock
'// all subsequent restore operations, and will prevent the restore target
'// from starting until the call to CertSrvRestoreRegisterComplete is made.
'//
'// Parameters:
'// [in] hbc - backup context handle for the restore session.
'// [in] pwszCheckPointFilePath - path to restore the check point files
'// [in] pwszLogPath - path where the log files are restored
'// [in] rgrstmap - restore map
'// [in] crstmap - tells if there is a new restore map
'// [in] pwszBackupLogPath - 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
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
' There is not ansi version
DECLARE FUNCTION CertSrvRestoreRegisterW LIB "certadm.dll" ALIAS "CertSrvRestoreRegisterW" ( BYVAL hbc AS QUAD , BYREF pwszCheckPointFilePath AS WSTRINGZ , BYREF pwszLogPath AS WSTRINGZ , BYREF rgrstmap AS CSEDB_RSTMAPW , BYVAL crstmap AS LONG , BYREF pwszBackupLogPath AS WSTRINGZ , BYVAL genLow AS QUAD , BYVAL genHigh AS QUAD ) AS LONG
MACRO CertSrvRestoreRegister = CertSrvRestoreRegisterW
DECLARE FUNCTION CertSrvRestoreRegisterThroughFile LIB "certadm.dll" ALIAS "CertSrvRestoreRegisterThroughFile" ( BYVAL hbc AS QUAD , BYREF pwszCheckPointFilePath AS WSTRINGZ , BYREF pwszLogPath AS WSTRINGZ , BYREF rgrstmap AS CSEDB_RSTMAPW , BYVAL crstmap AS LONG , BYREF pwszBackupLogPath AS WSTRINGZ , BYVAL genLow AS QUAD , BYVAL genHigh AS QUAD ) AS LONG
'//+--------------------------------------------------------------------------
'// CertSrvRestoreRegisterComplete -- indicate that a previously registered
'// restore is complete.
'//
'// Parameters:
'// [in] hbc - backup context handle
'// [in] hrRestoreState - success code if the restore was successful
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
DECLARE FUNCTION CertSrvRestoreRegisterComplete LIB "certadm.dll" ALIAS "CertSrvRestoreRegisterComplete" ( BYVAL hbc AS QUAD , BYVAL hrRestoreState AS LONG ) AS LONG
'//+--------------------------------------------------------------------------
'// CertSrvRestoreEnd -- end a restore session
'//
'// Parameters:
'// [in] hbc - backup context handle
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
DECLARE FUNCTION CertSrvRestoreEnd LIB "certadm.dll" ALIAS "CertSrvRestoreEnd" ( BYVAL hbc AS QUAD ) AS LONG
'//+--------------------------------------------------------------------------
'// CertSrvServerControl -- send a control command to the cert server.
'//
'// Parameters:
'// [in] pwszServerName - name or config string of the server to control
'// [in] dwControlFlags - control command and flags
'// [out] pcbOut - pointer to receive the size of command output data
'// [out] ppbOut - pointer to receive command output data. Use the
'// CertSrvBackupFree() API to free the buffer.
'//
'// Returns:
'// S_OK if the call executed successfully;
'// Failure code otherwise.
'//---------------------------------------------------------------------------
%EQUATE `CSCONTROL_SHUTDOWN = &H000000001
%EQUATE `CSCONTROL_SUSPEND = &H000000002
%EQUATE `CSCONTROL_RESTART = &H000000003
' There is not ansi version
DECLARE FUNCTION CertSrvServerControlW LIB "certadm.dll" ALIAS "CertSrvServerControlW" ( BYREF pwszServerName AS WSTRINGZ , BYVAL dwControlFlags AS QUAD , OPTIONAL BYREF pcbOut AS QUAD , OPTIONAL BYVAL ppbOut AS QUAD ) AS LONG
MACRO CertSrvServerControl = CertSrvServerControlW
#ENDIF
