/*============================================================================= Copyright (c) 2002 Microsoft Corporation Module Name: Txfw32.h Abstract: Header for the exported API set for the Txf Win32 API dynamic link library. Author: Jacob Lacouture [jacobl] May 9, 2002 Environment: User Mode Revision History: =============================================================================*/ #include #ifndef _TXF_W32_H_INCLUDED_ #define _TXF_W32_H_INCLUDED_ // // These are the different types of replication records that may be read from the log. // #define TXF_LOG_RECORD_TYPE_WRITE 0x01 #define TXF_LOG_RECORD_TYPE_TRUNCATE 0x02 #define TXF_LOG_RECORD_TYPE_AFFECTED_FILE 0x04 #define TXF_LOG_RECORD_GENERIC_TYPE_COMMIT 0x01 #define TXF_LOG_RECORD_GENERIC_TYPE_ABORT 0x02 #define TXF_LOG_RECORD_GENERIC_TYPE_PREPARE 0x04 #define TXF_LOG_RECORD_GENERIC_TYPE_DATA 0x08 // // Define alignment for all replication records. // #pragma pack(4) // // The TXF_ID is exposed as a 128 bit structure. This should NOT be treated as a GUID, in // that this is a unique identifier only within the context of the RM. These may collide // between different RMs. // typedef struct _TXF_ID { struct { LONGLONG LowPart; LONGLONG HighPart; }; } TXF_ID, *PTXF_ID; typedef GUID *PGUID; // // This is the basic record. If the entire record cannot be copied into the user's buffer, // at least this much may be copied if the buffer is big enough, so that the user can // determine how large a buffer he needs. // typedef struct _TXF_LOG_RECORD_BASE { // // This is a version identifier for the replication record generated by TXF. // USHORT Version; // // Type of record, defined above. // USHORT RecordType; // // Length of this record in bytes. // ULONG RecordLength; } TXF_LOG_RECORD_BASE, *PTXF_LOG_RECORD_BASE; // // This indicates a write. If this write goes beyond the end of the file, that implies // an extension of the file. // typedef struct _TXF_LOG_RECORD_WRITE { // // This is a version identifier for the replication record generated by TXF. // USHORT Version; // // Type of record, defined above. // USHORT RecordType; // // Length of this record in bytes. // ULONG RecordLength; // // Record flags. (none currently defined) // ULONG Flags; // // TxfFileId for the file this record refers to. // TXF_ID TxfFileId; // // This is the KTM transaction GUID for this update. // GUID KtmGuid; // // Beginning location of the write, as an offset from the beginning of the file. // LONGLONG ByteOffsetInFile; // // Number of bytes written. // ULONG NumBytesWritten; // // Offset of the redo data (bytes written) from the beginning of this record. // ULONG ByteOffsetInStructure; // // Length of the file name, in bytes. // ULONG FileNameLength; // // Offset of the file name from the beginning of this record. // ULONG FileNameByteOffsetInStructure; } TXF_LOG_RECORD_WRITE, *PTXF_LOG_RECORD_WRITE; // // This is a truncate record. // typedef struct _TXF_LOG_RECORD_TRUNCATE { // // This is a version identifier for the replication record generated by TXF. // USHORT Version; // // Type of record, defined above. // USHORT RecordType; // // Length of this record in bytes. // ULONG RecordLength; // // Record flags. (none currently defined) // ULONG Flags; // // TxfFileId for the file this record refers to. // TXF_ID TxfFileId; // // This is the KTM transaction GUID for this update. // GUID KtmGuid; // // New size of the file. // LONGLONG NewFileSize; // // Length of the file name, in bytes. // ULONG FileNameLength; // // Offset of the file name from the beginning of this record. // ULONG FileNameByteOffsetInStructure; } TXF_LOG_RECORD_TRUNCATE, *PTXF_LOG_RECORD_TRUNCATE; // // This structure describes a file that was affected by // a transaction in a given virtual clock range. // typedef struct _TXF_LOG_RECORD_AFFECTED_FILE { // // This is a version identifier for the replication record generated by TXF. // USHORT Version; // // Length of this record in bytes. // ULONG RecordLength; // // Record flags. (none currently defined) // ULONG Flags; // // TxfFileId for the file this record refers to. // TXF_ID TxfFileId; // // This is the KTM transaction GUID for this update. // GUID KtmGuid; // // Length of the file name, in bytes. // ULONG FileNameLength; // // Offset of the file name from the beginning of this record. // ULONG FileNameByteOffsetInStructure; } TXF_LOG_RECORD_AFFECTED_FILE, *PTXF_LOG_RECORD_AFFECTED_FILE; #pragma pack() // // The following are implemented in the TxfW32.dll module // #ifdef __cplusplus extern "C" { #endif BOOL WINAPI TxfLogCreateFileReadContext ( __in LPCWSTR LogPath, __in CLFS_LSN BeginningLsn, __in CLFS_LSN EndingLsn, __in PTXF_ID TxfFileId, __deref_out PVOID *TxfLogContext ); /* Description: This context will be required to read any replication records. In order to recover resources, the context must later be closed by calling TxfLogDestroyReadContext. Since the resources are allocated by a user-mode process, if that routine is not called, the resources will be recovered automatically when the process hosting the DLL terminates. Parameter Definition: LogPath - Location of the RM's CLFS BLF. BeginningLsn - Start of LSN range to search. (inclusive) EndingLsn - End of LSN range to search. (inclusive) TxfFileId - TxfId to scan the log for. TxfLogContext - Pointer to new TxfLogContext */ BOOL WINAPI TxfLogCreateRangeReadContext ( __in LPCWSTR LogPath, __in CLFS_LSN BeginningLsn, __in CLFS_LSN EndingLsn, __in PLARGE_INTEGER BeginningVirtualClock, __in PLARGE_INTEGER EndingVirtualClock, __in ULONG RecordTypeMask, __deref_out PVOID *TxfLogContext ); /* Description: This context will be required to read any replication records. In order to recover resources, the context must later be closed by calling TxfLogDestroyReadContext. Since the resources are allocated by a user-mode process, if that routine is not called, the resources will be recovered automatically when the process hosting the DLL terminates. Parameter Definition: LogPath - Location of the RM's CLFS BLF. BeginningLsn - Start of LSN range to search. (inclusive) EndingLsn - End of LSN range to search. (inclusive) TxfFileId - TxfId to scan the log for. TxfLogContext - Pointer to new TxfLogContext */ BOOL WINAPI TxfLogDestroyReadContext ( __in PVOID TxfLogContext ); /* Description: See comments for TxfLogCreateReadContext Parameter Definition: TxfLogContext - Pointer to TxfLogContext to destroy. */ BOOL WINAPI TxfLogReadRecords ( __in PVOID TxfLogContext, __in ULONG BufferLength, __out_bcount_part(BufferLength, *BytesUsed) PVOID Buffer, __out PULONG BytesUsed, __out PULONG RecordCount ); /* Description: If all of the available records were copied into the buffer, TRUE will be returned. Otherwise, the return value will be FALSE. If FALSE is returned, LastError should be checked. Possible values for LastError are: ERROR_INVALID_HANDLE - The replication context is invalid. ERROR_MORE_DATA - Some records were copied into the buffer. This routine should be called again to retrieve the rest. ERROR_INSUFFICIENT_BUFFER - There wasn't sufficient buffer space to even copy one record. If this is set, check the value of BytesUsed. If this is nonzero, then there was enough space to copy the TXF_LOG_RECORD_BASE record, which indicates how large a buffer is needed to read the next complete record. Call back with a buffer at least that size. If BytesUsed is zero, the buffer provided to this routine was far too small. Try again with a larger buffer. ERROR_FILE_CORRUPT - The format of the log file being processed is unrecognized. Other error codes may be returned by CLFS. -------------------------------------------------------------------------------------- NOTE: This routine will return all redo records in the log except for CLRs. This means that the replication client must be intelligent enough to discard records for transactions that will ultimately abort. We provide the KTM GUID in each replication record to assist in this filtering. Alternatively, the replication client could query the last LSN after each abort and commit are complete. The scan could then be done only for ranges in which all the records are for committed transactions. -------------------------------------------------------------------------------------- Parameter Definition: TxfLogContext - Pointer to TxfLogContext BufferLength - Length of buffer passed to this routine (in bytes) Buffer - Address of buffer to copy records into. BytesUsed - Amount of buffer actually used. RecordCount - Number of records copied into the buffer. */ BOOL WINAPI TxfReadMetadataInfo ( __in HANDLE FileHandle, __out PTXF_ID TxfFileId, __out PCLFS_LSN LastLsn, __out PULONG TransactionState, __out PGUID LockingTransaction ); /* Description: This routine will retrieve the TxfFileId, most recent LSN, and locking transaction (if applicable) for the specified file. If the file has not had any transacted work done on it, it will have none of these properties and this call will return failure. Parameter Definition: FileHandle - File to read the information for. TxfFileId - Returned TxfId of the file. LastLsn - Returned LastLsn for the file. TransactionState - The state of the transaction locking this file. LockingTransaction - If TransactionState != TXFS_TRANSACTION_STATE_NONE, the GUID of the transaction locking the file. Otherwise, this value has no meaning. */ BOOL WINAPI TxfLogRecordGetFileName ( __in_bcount(RecordBufferLengthInBytes) PVOID RecordBuffer, __in ULONG RecordBufferLengthInBytes, __out_bcount(NameBufferLengthInBytes) PWSTR NameBuffer, __inout PULONG NameBufferLengthInBytes, __out_opt PTXF_ID TxfId ); /* Description: This routine will decode a TXF log record and copy the name of the file referred to by the record and optionally the TXF ID for it. Parameter Definition: RecordBuffer - The TXF log record. RecordBufferLengthInBytes - Length of RecordBuffer. NameBuffer - Returned name of the file referred to by RecordBuffer. NameBuffer - Supplied length of NameBuffer and returned length or required length if buffer is too short. TxfFileId - Returned TxfId of the file. */ BOOL WINAPI TxfLogRecordGetGenericType ( __in PVOID RecordBuffer, __in ULONG RecordBufferLengthInBytes, __out PULONG GenericType, __out_opt PLARGE_INTEGER VirtualClock ); /* Description: This routine will decode a TXF log record and determine what type of record it is (commit, undo, etc.). If the type has a virtual clock associated with it, then that is returned as well. Parameter Definition: RecordBuffer - The TXF log record. RecordBufferLengthInBytes - Length of RecordBuffer. GenericType - Returned type of record. VirtualClock - Virtual clock if the type has one (0 if not present). */ VOID WINAPI TxfSetThreadMiniVersionForCreate ( __in USHORT MiniVersion ); /* Description: This routine is used to set the MiniVersion that a subsequent create should open. It should be returned to its previous state after calling create. Therefore, prior to calling this routine, the caller should invoke TxfGetThreadMiniVersionForCreate. Parameter Definition: MiniVersion - A USHORT identifying which version should be opened by create. */ VOID WINAPI TxfGetThreadMiniVersionForCreate ( __out PUSHORT MiniVersion ); /* Description: This routine returns what MiniVersion a subsequent create is set to open. Parameter Definition: MiniVersion - Pointer to a USHORT which will receive the result. */ // // Either of these constants may be used to identify the miniversion to open. // #define TXFS_MINIVERSION_COMMITTED_VIEW (0x0000) #define TXFS_MINIVERSION_DIRTY_VIEW (0xFFFF) #define TXFS_MINIVERSION_DEFAULT_VIEW (0xFFFE) #ifdef __cplusplus // // extern "C" // } #endif //_TXF_W32_H_INCLUDED_ #endif