NtCreateTransaction 함수(wdm.h)

아티클
03/14/2023

ZwCreateTransaction 루틴은 트랜잭션 개체를 만듭니다.

구문

__kernel_entry NTSYSCALLAPI NTSTATUS NtCreateTransaction(
  [out]          PHANDLE            TransactionHandle,
  [in]           ACCESS_MASK        DesiredAccess,
  [in, optional] POBJECT_ATTRIBUTES ObjectAttributes,
  [in, optional] LPGUID             Uow,
  [in, optional] HANDLE             TmHandle,
  [in, optional] ULONG              CreateOptions,
  [in, optional] ULONG              IsolationLevel,
  [in, optional] ULONG              IsolationFlags,
  [in, optional] PLARGE_INTEGER     Timeout,
  [in, optional] PUNICODE_STRING    Description
);

매개 변수

[out] TransactionHandle

ZwCreateTransaction에 대한 호출이 성공하는 경우 새 트랜잭션 개체에 대한 핸들을 수신하는 호출자가 할당한 변수에 대한 포인터입니다.

[in] DesiredAccess

트랜잭션 개체에 대한 호출자의 요청된 액세스를 지정하는 ACCESS_MASK 값입니다. 호출자는 모든 종류의 개체에 대해 정의된 액세스 권한( ACCESS_MASK 참조) 외에도 트랜잭션 개체에 대해 다음 플래그를 지정할 수 있습니다.

액세스 마스크	호출자가 다음을 할 수 있도록 허용
TRANSACTION_COMMIT	트랜잭션을 커밋합니다( ZwCommitTransaction 참조).
TRANSACTION_ENLIST	트랜잭션에 대한 인리스트먼트를 만듭니다( ZwCreateEnlistment 참조).
TRANSACTION_PROPAGATE	사용하지 마십시오.
TRANSACTION_QUERY_INFORMATION	트랜잭션에 대한 정보를 가져옵니다( ZwQueryInformationTransaction 참조).
TRANSACTION_ROLLBACK	트랜잭션 롤백( ZwRollbackTransaction 참조).
TRANSACTION_SET_INFORMATION	트랜잭션에 대한 정보를 설정합니다( ZwSetInformationTransaction 참조).

또는 다음 ACCESS_MASK 비트맵 중 하나 이상을 지정할 수 있습니다. 이러한 비트맵은 이전 테이블의 플래그를 ACCESS_MASK 참조 페이지에 설명된 STANDARD_RIGHTS_XXX 플래그와 결합합니다. 이러한 비트맵을 이전 테이블의 추가 플래그와 결합할 수도 있습니다. 다음 표에서는 비트맵이 특정 액세스 권한에 해당하는 방법을 보여줍니다.

권한 비트맵	특정 액세스 권한 집합
TRANSACTION_GENERIC_READ	STANDARD_RIGHTS_READ, TRANSACTION_QUERY_INFORMATION 및 SYNCHRONIZE
TRANSACTION_GENERIC_WRITE	STANDARD_RIGHTS_WRITE, TRANSACTION_SET_INFORMATION, TRANSACTION_COMMIT, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE, TRANSACTION_SAVEPOINT 및 SYNCHRONIZE
TRANSACTION_GENERIC_EXECUTE	STANDARD_RIGHTS_EXECUTE, TRANSACTION_COMMIT, TRANSACTION_ROLLBACK 및 SYNCHRONIZE
TRANSACTION_ALL_ACCESS	STANDARD_RIGHTS_REQUIRED, TRANSACTION_GENERIC_READ, TRANSACTION_GENERIC_WRITE 및 TRANSACTION_GENERIC_EXECUTE
TRANSACTION_RESOURCE_MANAGER_RIGHTS	STANDARD_RIGHTS_WRITE, TRANSACTION_GENERIC_READ, TRANSACTION_SET_INFORMATION, TRANSACTION_ENLIST, TRANSACTION_ROLLBACK, TRANSACTION_PROPAGATE 및 SYNCHRONIZE

일반적으로 리소스 관리자는 TRANSACTION_RESOURCE_MANAGER_RIGHTS 지정합니다.

DesiredAccess 값은 0일 수 없습니다.

[in, optional] ObjectAttributes

개체 이름 및 기타 특성을 지정하는 OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. InitializeObjectAttributes 루틴을 사용하여 이 구조를 초기화합니다. 호출자가 시스템 스레드 컨텍스트에서 실행되고 있지 않으면 InitializeObjectAttributes를 호출할 때 OBJ_KERNEL_HANDLE 특성을 설정해야 합니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

[in, optional] Uow

KTM이 새 트랜잭션 개체의 UOW(작업 단위) 식별자로 사용하는 GUID에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다. 이 매개 변수가 NULL이면 KTM은 GUID를 생성하고 트랜잭션 개체에 할당합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

[in, optional] TmHandle

ZwCreateTransactionManager 또는 ZwOpenTransactionManager에 대한 이전 호출에서 가져온 트랜잭션 관리자 개체 에 대한 핸들입니다. KTM은 지정된 트랜잭션 관리자 개체에 새 트랜잭션 개체를 할당합니다. 이 매개 변수가 NULL인 경우 KTM은 나중에 리소스 관리자가 트랜잭션에 대한 인리스트먼트를 만들 때 새 트랜잭션 개체를 트랜잭션 관리자에 할당합니다.

[in, optional] CreateOptions

선택적 개체 만들기 플래그입니다. 다음 표에는 Ktmtypes.h에 정의된 사용 가능한 플래그가 포함되어 있습니다.

옵션 플래그	의미
TRANSACTION_DO_NOT_PROMOTE	나중에 사용하기 위해 예약되어 있습니다.

[in, optional] IsolationLevel

나중에 사용하기 위해 예약되어 있습니다. 호출자는 이 매개 변수를 0으로 설정해야 합니다.

[in, optional] IsolationFlags

다음에 사용하도록 예약됩니다. 호출자는 이 매개 변수를 0으로 설정해야 합니다.

[in, optional] Timeout

제한 시간 값에 대한 포인터입니다. 이 매개 변수에 지정된 시간까지 트랜잭션이 커밋되지 않은 경우 KTM은 트랜잭션을 롤백합니다. 제한 시간 값은 시스템 시간 단위(100나노초 간격)로 표현되며 절대 시간 또는 상대 시간을 지정할 수 있습니다. Timeout에서 가리키는 값이 음수이면 만료 시간은 현재 시스템 시간을 기준으로 합니다. 그렇지 않으면 만료 시간이 절대입니다. 이 포인터는 선택 사항이며 트랜잭션에 제한 시간 값이 없도록 하려면 NULL 일 수 있습니다. Timeout = NULL 또는 *Timeout = 0이면 트랜잭션 시간이 초과되지 않습니다. (ZwSetInformationTransaction을 사용하여 제한 시간 값을 설정할 수도 있습니다.)

[in, optional] Description

NULL로 끝나는 문자열을 포함하는 호출자가 제공한 UNICODE_STRING 구조체에 대한 포인터입니다. 문자열은 트랜잭션에 대한 설명을 제공합니다. KTM은 문자열의 복사본을 저장하고 로그 스트림에 쓰는 메시지에 문자열을 포함합니다. 최대 문자열 길이는 MAX_TRANSACTION_DESCRIPTION_LENGTH. 이 매개 변수는 선택 사항이며 NULL일 수 있습니다.

반환 값

ZwCreateTransaction은 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 이 루틴이 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	CreateOptions 매개 변수에 잘못된 플래그가 포함되어 있거나 DesiredAccess 매개 변수가 0이거나 Description 매개 변수의 문자열이 너무 깁니다.
STATUS_INSUFFICIENT_RESOURCES	KTM은 시스템 리소스(일반적으로 메모리)를 할당할 수 없습니다.
STATUS_INVALID_ACL	보안 설명자에 잘못된 ACL(액세스 제어 목록)이 포함되어 있습니다.
STATUS_INVALID_SID	보안 설명자에 잘못된 SID(보안 식별자)가 포함되어 있습니다.
STATUS_OBJECT_NAME_EXISTS	ObjectAttributes 매개 변수가 지정하는 개체 이름이 이미 있습니다.
STATUS_OBJECT_NAME_INVALID	ObjectAttributes 매개 변수가 지정하는 개체 이름이 잘못되었습니다.
STATUS_ACCESS_DENIED	DesiredAccess 매개 변수의 값이 잘못되었습니다.

루틴은 다른 NTSTATUS 값을 반환할 수 있습니다.

설명

호출자는 Uow 매개 변수를 사용하여 트랜잭션 개체에 대한 UOW 식별자를 지정할 수 있습니다. 호출자가 UOW 식별자를 지정하지 않으면 KTM은 GUID를 생성하고 트랜잭션 개체에 할당합니다. 호출자는 나중에 ZwQueryInformationTransaction을 호출하여 이 GUID를 가져올 수 있습니다.

일반적으로 구성 요소가 트랜잭션에 대한 UOW 식별자를 이미 생성한 다른 TPS 구성 요소와 통신하지 않는 한 KTM에서 트랜잭션 개체에 대한 GUID를 생성하도록 해야 합니다.

트랜잭션 핸들을 닫기 위해 ZwCreateTransaction 이라는 구성 요소는 ZwClose를 호출해야 합니다. 구성 요소가 트랜잭션에 대해 ZwCommitTransaction 을 호출하기 전에 마지막 트랜잭션 핸들이 닫히면 KTM은 트랜잭션을 롤백합니다.

트랜잭션 클라이언트에서 ZwCreateTransaction을 사용하는 방법에 대한 자세한 내용은 트랜잭션 클라이언트 만들기를 참조하세요.

커널 모드 드라이버에서 호출하는 경우 Windows 네이티브 시스템 서비스 루틴의 NtXxx 및 ZwXxx 버전은 입력 매개 변수를 처리하고 해석하는 방식으로 다르게 동작할 수 있습니다. 루틴의 NtXxx 버전과 ZwXxx 버전 간의 관계에 대한 자세한 내용은 네이티브 시스템 서비스 루틴의 Nt 및 Zw 버전 사용을 참조하세요.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista 이상 운영 체제 버전에서 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs, PowerIrpDDis