Skip to content

Latest commit

 

History

History
501 lines (319 loc) · 15.1 KB

catltransactionmanager-class.md

File metadata and controls

501 lines (319 loc) · 15.1 KB
Raw
description title ms.date f1_keywords helpviewer_keywords ms.assetid
Learn more about: CAtlTransactionManager Class
CAtlTransactionManager Class
11/04/2016
CAtlTransactionManager
ATLTRANSACTIONMANAGER/ATL::CAtlTransactionManager
ATLTRANSACTIONMANAGER/ATL::Close
ATLTRANSACTIONMANAGER/ATL::Commit
ATLTRANSACTIONMANAGER/ATL::Create
ATLTRANSACTIONMANAGER/ATL::CreateFile
ATLTRANSACTIONMANAGER/ATL::DeleteFile
ATLTRANSACTIONMANAGER/ATL::FindFirstFile
ATLTRANSACTIONMANAGER/ATL::GetFileAttributes
ATLTRANSACTIONMANAGER/ATL::GetFileAttributesEx
ATLTRANSACTIONMANAGER/ATL::GetHandle
ATLTRANSACTIONMANAGER/ATL::IsFallback
ATLTRANSACTIONMANAGER/ATL::MoveFile
ATLTRANSACTIONMANAGER/ATL::RegCreateKeyEx
ATLTRANSACTIONMANAGER/ATL::RegDeleteKey
ATLTRANSACTIONMANAGER/ATL::RegOpenKeyEx
ATLTRANSACTIONMANAGER/ATL::Rollback
ATLTRANSACTIONMANAGER/ATL::SetFileAttributes
ATLTRANSACTIONMANAGER/ATL::m_bFallback
ATLTRANSACTIONMANAGER/ATL::m_hTransaction
CAtlTransactionManager class
b01732dc-1d16-4b42-bfac-b137fca2b740

CAtlTransactionManager Class

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

Important

This class and its members cannot be used in applications that execute in the Windows Runtime.

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