CAtlTransactionManager Class

CAtlTransactionManager class provides a wrapper to Kernel Transaction Manager (KTM) functions.

Syntax

class CAtlTransactionManager;

Members

Public Constructors

Name	Description
~CAtlTransactionManager	CAtlTransactionManager destructor.
CAtlTransactionManager	CAtlTransactionManager constructor.

Public Methods

Name	Description
Close	Closes one the transaction handle.
Commit	Requests that the transaction be committed.
Create	Creates the transaction handle.
CreateFile	Creates or opens a file, file stream, or directory as a transacted operation.
DeleteFile	Deletes an existing file as a transacted operation.
FindFirstFile	Searches a directory for a file or subdirectory as a transacted operation.
GetFileAttributes	Retrieves file system attributes for a specified file or directory as a transacted operation.
GetFileAttributesEx	Retrieves file system attributes for a specified file or directory as a transacted operation.
GetHandle	Returns the transaction handle.
IsFallback	Determines whether the fallback calls are enabled.
MoveFile	Moves an existing file or a directory, including its children, as a transacted operation.
RegCreateKeyEx	Creates the specified registry key and associates it with a transaction. If the key already exists, the function opens it.
RegDeleteKey	Deletes a subkey and its values from the specified platform-specific view of the registry as a transacted operation.
RegOpenKeyEx	Opens the specified registry key and associates it with a transaction.
Rollback	Requests that the transaction be rolled back.
SetFileAttributes	Sets the attributes for a file or directory as a transacted operation.

Protected Data Members

Name	Description
m_bFallback	TRUE if the fallback is supported; FALSE otherwise.
m_hTransaction	The transaction handle.

Remarks

Inheritance Hierarchy

ATL::CAtlTransactionManager

Requirements

Header: atltransactionmanager.h

~CAtlTransactionManager

CAtlTransactionManager destructor.

virtual ~CAtlTransactionManager();

Remarks

In normal processing, the transaction is automatically committed and closed. If the destructor is called during an exception unwind, the transaction is rolled back and closed.

CAtlTransactionManager

CAtlTransactionManager constructor.

CAtlTransactionManager(BOOL bFallback = TRUE, BOOL bAutoCreateTransaction = TRUE);

Parameters

bFallback
TRUE indicates support fallback. If transacted function fails, the class automatically calls the "non-transacted" function. FALSE indicates no "fallback" calls.

bAutoCreateTransaction
TRUE indicates that the transaction handler is created automatically in the constructor. FALSE indicates that it is not.

Remarks

Close

Closes the transaction handle.

inline BOOL Close();

Return Value

TRUE if successful; otherwise FALSE.

Remarks

This wrapper calls the CloseHandle function. The method is automatically called in the destructor.

Commit

Requests that the transaction be committed.

inline BOOL Commit();

Return Value

TRUE if successful; otherwise FALSE.

Remarks

This wrapper calls the CommitTransaction function. The method is automatically called in the destructor.

Create

Creates the transaction handle.

inline BOOL Create();

Return Value

TRUE if successful; otherwise FALSE.

Remarks

This wrapper calls the CreateTransaction function. Check it for

CreateFile

Creates or opens a file, file stream, or directory as a transacted operation.

inline HANDLE CreateFile(
    LPCTSTR lpFileName,
    DWORD dwDesiredAccess,
    DWORD dwShareMode,
    LPSECURITY_ATTRIBUTES lpSecurityAttributes,
    DWORD dwCreationDisposition,
    DWORD dwFlagsAndAttributes,
    HANDLE hTemplateFile);

Parameters

lpFileName
The name of an object to be created or opened.

dwDesiredAccess
The access to the object, which can be summarized as read, write, both, or neither (zero). The most commonly used values are GENERIC_READ, GENERIC_WRITE, or both: GENERIC_READ | GENERIC_WRITE.

dwShareMode
The sharing mode of an object, which can be read, write, both, delete, all of these, or none: 0, FILE_SHARE_DELETE, FILE_SHARE_READ, FILE_SHARE_WRITE.

lpSecurityAttributes
A pointer to a SECURITY_ATTRIBUTES structure that contains an optional security descriptor and also determines whether or not the returned handle can be inherited by child processes. The parameter can be NULL.

dwCreationDisposition
An action to take on files that exist and do not exist. This parameter must be one of the following values, which cannot be combined: CREATE_ALWAYS, CREATE_NEW, OPEN_ALWAYS, OPEN_EXISTING, or TRUNCATE_EXISTING.

dwFlagsAndAttributes
The file attributes and flags. This parameter can include any combination of the available file attributes (FILE_ATTRIBUTE_*). All other file attributes override FILE_ATTRIBUTE_NORMAL. This parameter can also contain combinations of flags (FILE_FLAG_*) for control of buffering behavior, access modes, and other special-purpose flags. These combine with any FILE_ATTRIBUTE_* values.

hTemplateFile
A valid handle to a template file with the GENERIC_READ access right. The template file supplies file attributes and extended attributes for the file that is being created. This parameter can be NULL.

Return Value

Returns a handle that can be used to access the object.

Remarks

This wrapper calls the CreateFileTransacted function.

DeleteFile

Deletes an existing file as a transacted operation.

inline BOOL DeleteFile(LPCTSTR lpFileName);

Parameters

lpFileName
The name of the file to be deleted.

Remarks

This wrapper calls the DeleteFileTransacted function.

FindFirstFile

Searches a directory for a file or subdirectory as a transacted operation.

inline HANDLE FindFirstFile(
    LPCTSTR lpFileName,
    WIN32_FIND_DATA* pNextInfo);

Parameters

lpFileName
The directory or path, and the file name to search for. This parameter can include wildcard characters, such as an asterisk (*) or a question mark ().

pNextInfo
A pointer to the WIN32_FIND_DATA structure that receives information about a found file or subdirectory.

Return Value

If the function succeeds, the return value is a search handle used in a subsequent call to FindNextFile or FindClose. If the function fails or fails to locate files from the search string in the lpFileName parameter, the return value is INVALID_HANDLE_VALUE.

Remarks

This wrapper calls the FindFirstFileTransacted function.

GetFileAttributes

Retrieves file system attributes for a specified file or directory as a transacted operation.

inline DWORD GetFileAttributes(LPCTSTR lpFileName);

Parameters

lpFileName
The name of the file or directory.

Remarks

This wrapper calls the GetFileAttributesTransacted function.

GetFileAttributesEx

Retrieves file system attributes for a specified file or directory as a transacted operation.

inline BOOL GetFileAttributesEx(
    LPCTSTR lpFileName,
    GET_FILEEX_INFO_LEVELS fInfoLevelId,
    LPVOID lpFileInformation);

Parameters

lpFileName
The name of the file or directory.

fInfoLevelId
The level of attribute information to retrieve.

lpFileInformation
A pointer to a buffer that receives the attribute information. The type of attribute information that is stored into this buffer is determined by the value of fInfoLevelId. If the fInfoLevelId parameter is GetFileExInfoStandard then this parameter points to a WIN32_FILE_ATTRIBUTE_DATA structure.

Remarks

This wrapper calls the GetFileAttributesTransacted function.

GetHandle

Returns the transaction handle.

HANDLE GetHandle() const;

Return Value

Returns the transaction handle for a class. Returns NULL if the CAtlTransactionManager is not attached to a handle.

Remarks

IsFallback

Determines whether the fallback calls are enabled.

BOOL IsFallback() const;

Return Value

Returns TRUE is the class supports fallback calls. FALSE otherwise.

Remarks

m_bFallback

TRUE if the fallback is supported; FALSE otherwise.

BOOL m_bFallback;

Remarks

m_hTransaction

The transaction handle.

HANDLE m_hTransaction;

Remarks

MoveFile

Moves an existing file or a directory, including its children, as a transacted operation.

inline BOOL MoveFile(LPCTSTR lpOldFileName, LPCTSTR lpNewFileName);

Parameters

lpOldFileName
The current name of the existing file or directory on the local computer.

lpNewFileName
The new name for the file or directory. This name must not already exist. A new file may be on a different file system or drive. A new directory must be on the same drive.

Remarks

This wrapper calls the MoveFileTransacted function.

RegCreateKeyEx

Creates the specified registry key and associates it with a transaction. If the key already exists, the function opens it.

inline LSTATUS RegCreateKeyEx(
    HKEY hKey,
    LPCTSTR lpSubKey,
    DWORD dwReserved,
    LPTSTR lpClass,
    DWORD dwOptions,
    REGSAM samDesired,
    CONST LPSECURITY_ATTRIBUTES lpSecurityAttributes,
    PHKEY phkResult,
    LPDWORD lpdwDisposition);

Parameters

hKey
A handle to an open registry key.

lpSubKey
The name of a subkey that this function opens or creates.

dwReserved
This parameter is reserved and must be zero.

lpClass
The user-defined class of this key. This parameter may be ignored. This parameter can be NULL.

dwOptions
This parameter can be one of the following values: REG_OPTION_BACKUP_RESTORE, REG_OPTION_NON_VOLATILE, or REG_OPTION_VOLATILE.

samDesired
A mask that specifies the access rights for the key.

lpSecurityAttributes
Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

phkResult
A pointer to a variable that receives a handle to the opened or created key. If the key is not one of the predefined registry keys, call the RegCloseKey function after you have finished using the handle.

lpdwDisposition
A pointer to a variable that receives one of the following disposition values: REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h.

Remarks

This wrapper calls the RegCreateKeyTransacted function.

RegDeleteKey

Deletes a subkey and its values from the specified platform-specific view of the registry as a transacted operation.

inline LSTATUS RegDeleteKeyEx(HKEY hKey, LPCTSTR lpSubKey);

Parameters

hKey
A handle to an open registry key.

lpSubKey
The name of the key to be deleted.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h.

Remarks

This wrapper calls the RegDeleteKeyTransacted function.

RegOpenKeyEx

Opens the specified registry key and associates it with a transaction.

inline LSTATUS RegOpenKeyEx(
    HKEY hKey,
    LPCTSTR lpSubKey,
    DWORD ulOptions,
    REGSAM samDesired,
    PHKEY phkResult);

Parameters

hKey
A handle to an open registry key.

lpSubKey
The name of the registry subkey to be opened.

ulOptions
This parameter is reserved and must be zero.

samDesired
A mask that specifies the access rights for the key.

phkResult
A pointer to a variable that receives a handle to the opened or created key. If the key is not one of the predefined registry keys, call the RegCloseKey function after you have finished using the handle.

Return Value

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h

Remarks

This wrapper calls the RegOpenKeyTransacted function.

Rollback

Requests that the transaction be rolled back.

inline BOOL Rollback();

Return Value

TRUE if successful; otherwise FALSE.

Remarks

This wrapper calls the RollbackTransaction function.

SetFileAttributes

Sets the attributes for a file or directory as a transacted operation.

inline BOOL SetFileAttributes(LPCTSTR lpFileName, DWORD dwAttributes);

Parameters

lpFileName
The name of the file or directory.

dwAttributes
The file attributes to set for the file. For more information, see SetFileAttributesTransacted.

Remarks

This wrapper calls the SetFileAttributesTransacted function.

See also

ATL COM Desktop Components