IPort::NewRegistryKey 메서드(portcls.h)

NewRegistryKey 메서드는 기존 레지스트리 키를 열거나 레지스트리에 새 키를 만듭니다. 메서드는 키를 나타내는 레지스트리 키 개체를 만들고 호출자에게 이 개체에 대한 참조를 출력합니다. 그런 다음 호출자는 개체의 IRegistryKey 인터페이스를 통해 키에 액세스합니다.

구문

NTSTATUS NewRegistryKey(
  PREGISTRYKEY       *OutRegistryKey,
  PUNKNOWN           OuterUnknown,
  ULONG              RegistryKeyType,
  ACCESS_MASK        DesiredAccess,
  POBJECT_ATTRIBUTES ObjectAttributes,
  ULONG              CreateOptions,
  PULONG             Disposition
);

매개 변수

OutRegistryKey

메서드가 IRegistryKey 개체에 대한 참조를 쓰는 호출자가 할당한 포인터 변수에 대한 포인터입니다. 이 개체는 열려 있거나 생성되는 레지스트리 키를 나타냅니다. 호출자는 이 매개 변수에 대해 유효한 NULL이 아닌 포인터 값을 지정해야 합니다.

OuterUnknown

레지스트리 키 개체를 집계해야 하는 개체의 IUnknown 인터페이스에 대한 포인터입니다. 이 매개 변수는 선택적 요소입니다. 집계가 필요하지 않은 경우 이 매개 변수를 NULL로 지정합니다.

RegistryKeyType

호출자가 액세스를 요청하는 레지스트리 키의 유형을 지정합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

DesiredAccess

호출자가 키에 필요한 액세스 유형을 지정하는 액세스 제어 마스크입니다. 이 매개 변수는 ACCESS_MASK 형식입니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

ObjectAttributes

만들거나 여는 키의 개체 특성에 대한 포인터입니다. RegistryKeyType에 GeneralRegistryKey 값이 있는 경우 이 매개 변수는 키에 유효한 ObjectName 문자열이 있는 OBJECT_ATTRIBUTES 형식의 유효한 초기화된 시스템 구조를 가리킵니다. 그렇지 않으면 메서드는 이 매개 변수를 사용하지 않습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

CreateOptions

만들기 옵션을 나타내는 플래그입니다. 원하는 항목이 없으면 0이 될 수 있습니다. RegistryKeyType 값이 GeneralRegistryKey인 경우 이 매개 변수가 필요합니다. 그렇지 않으면 메서드는 이 매개 변수를 사용하지 않습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

Disposition

메서드가 새 키를 만들었는지 또는 기존 키가 열렸는지를 나타내는 상태 값을 작성하는 호출자가 할당한 ULONG 변수에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 호출자에게 상태 값이 필요하지 않은 경우 NULL로 지정할 수 있습니다. 메서드는 RegistryKeyType 값이 GeneralRegistryKey인 경우에만 이 매개 변수를 사용합니다. 메서드는 다른 키 형식에 대해 매개 변수를 사용하지 않습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

반환 값

이 메서드는 호출이 성공한 경우 STATUS_SUCCESS 포함하는 NTSTATUS를 반환합니다. 그렇지 않으면 메서드는 적절한 오류 코드를 반환합니다.

설명

DesiredAccess, ObjectAttributes 및 Disposition 매개 변수는 ZwCreateKey 호출에서 이름이 같은 매개 변수에 대해 정의된 값을 사용합니다.

RegistryKeyType 매개 변수에 GeneralRegistryKey 값이 있는 경우 NewRegistryKey 메서드는 기존 레지스트리 키를 열거나 메서드가 Disposition 매개 변수를 통해 출력하는 값으로 표시된 대로 레지스트리에 새 키를 만듭니다. 키 형식이 GeneralRegistryKey 이외의 값인 경우 메서드는 플러그 앤 플레이 디바이스 열거 중에 이전에 만든 기존 키를 엽니다.

호출자는 RegistryKeyType 매개 변수를 다음 표에 표시된 열거형 값 중 하나로 설정해야 합니다.

RegistryKeyType 값	의미
GeneralRegistryKey	모든 키 형식에 대한 일반 액세스를 제공합니다. 키가 있는 경우 키를 열거나 키가 없는 경우 키를 만듭니다.
DeviceRegistryKey	디바이스별 정보가 포함된 기존 키를 엽니다.
DriverRegistryKey	드라이버 관련 정보가 포함된 기존 키를 엽니다.
HwProfileRegistryKey	디바이스 또는 드라이버 정보에 대한 현재 하드웨어 프로필을 기준으로 기존 키를 엽니다. 이렇게 하면 드라이버가 하드웨어 프로필 관련 구성 정보에 액세스할 수 있습니다.
DeviceInterfaceRegistryKey	특정 디바이스 인터페이스 instance 대한 정보가 포함된 기존 레지스트리 키를 엽니다.

GeneralRegistryKey의 RegistryKeyType 값의 경우 호출자는 유효한 ObjectAttributes 매개 변수 값을 제공해야 하며 CreateOptions 및 Disposition 매개 변수는 선택 사항입니다. 다른 RegistryKeyType 값의 경우 호출자는 유효한 DeviceObject 매개 변수 값을 제공해야 하며 CreateOptions 및 Disposition 매개 변수는 사용되지 않습니다.

ObjectAttributes 매개 변수는 키 이름 및 보안 설명자와 같은 개체 특성을 포함하는 OBJECT_ATTRIBUTES 형식의 불투명 구조를 가리킵니다. InitializeObjectAttributes 매크로를 사용하여 구조를 초기화합니다. 이 매크로의 Attributes 매개 변수에서 안전하지 않은 사용자 모드 애플리케이션이 레지스트리 키에 대한 읽기/쓰기 액세스를 허용하지 않는 한 OBJ_KERNEL_HANDLE 플래그를 설정합니다.

DesiredAccess 매개 변수는 액세스 제어 마스크입니다. OutRegistryKey 개체를 통해 액세스할 때 호출자가 새 레지스트리 키에 액세스해야 하는 액세스 제어 유형을 지정합니다. 이 마스크는 레지스트리 키에 대한 사용자의 액세스를 제어하는 ACL(액세스 제어 목록)과 혼동해서는 안 됩니다. NewRegistryKey를 호출하여 GeneralRegistryKey 형식의 레지스트리 키를 만들 때 ObjectAttributes 매개 변수는 ACL을 포함하는 보안 설명자를 포함하여 키의 특성을 지정합니다. 그러나 키 형식이 GeneralRegistryKey이고 ObjectAttributes 구조의 보안 설명자 포인터가 NULL이거나 보안 설명자의 ACL 포인터가 NULL인 경우 호출에서 만든 새 키는 기본적으로 부모 키의 ACL을 상속합니다.

키가 GeneralRegistryKey 형식이 아닌 경우 키는 디바이스 열거 중에 키에 할당된 플러그 앤 플레이 ACL을 유지합니다.

NewRegistryKey 메서드는 PcNewRegistryKey 호출에서 디바이스 개체 및 포트 개체를 명시적으로 지정해야 하지만 NewRegistryKey 호출에만 암시된다는 점을 제외하고 PcNewRegistryKey 함수와 유사합니다. PcNewRegistryKey는 일반적으로 어댑터 드라이버에서 호출됩니다. 미니포트 드라이버는 일반적으로 NewRegistryKey를 대신 호출합니다.

NewRegistryKey 또는 PcNewRegistryKey를 호출하여 레지스트리 키를 만들거나 열면 IRegistryKey::NewSubKey 메서드를 사용하여 해당 키 아래에 하위 키를 만들 수 있습니다.

OutRegistryKey 및 OuterUnknown 매개 변수는 COM 개체에 대한 참조 계산 규칙을 따릅니다.

요구 사항

요구 사항	값
헤더	portcls.h
IRQL	PASSIVE_LEVEL

추가 정보

IPort