IRegistryKey::NewSubKey 메서드(portcls.h)

아티클
08/07/2023

메서드는 NewSubKey 새 레지스트리 하위 키를 만들거나 IRegistryKey 개체가 나타내는 키 아래에 기존 하위 키를 엽니다.

구문

NTSTATUS NewSubKey(
  [out]           IRegistryKey    **RegistrySubKey,
  [in]            PUNKNOWN        OuterUnknown,
  [in]            ACCESS_MASK     DesiredAccess,
  [in]            PUNICODE_STRING SubKeyName,
  [in]            ULONG           CreateOptions,
  [out, optional] PULONG          Disposition
);

매개 변수

[out] RegistrySubKey

새 하위 키에 대한 출력 포인터입니다. 이 매개 변수는 메서드가 새 IRegistryKey 개체에 포인터를 쓰는 호출자 할당 포인터 변수를 가리킵니다. 이 개체는 열거나 만드는 하위 키를 나타냅니다. 이 매개 변수에 유효한 NULL 이 아닌 포인터 값을 지정합니다.

[in] OuterUnknown

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

[in] DesiredAccess

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

[in] SubKeyName

하위 키에 할당할 이름에 대한 포인터입니다. 이 매개 변수는 UNICODE_STRING 형식의 초기화된 구조에 대한 유효한 NULL이 아닌 포인터여야 합니다.

[in] CreateOptions

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

[out, optional] Disposition

처리 값에 대한 출력 포인터입니다. 이 매개 변수는 호출자가 할당한 ULONG 변수를 가리키며, 메서드는 새 키가 만들어졌는지 또는 기존 키가 열렸는지 여부를 나타내는 상태 값을 씁니다. 이 매개 변수는 선택 사항이며 호출자가 필요하지 않은 경우 NULL 로 지정할 수 있습니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

반환 값

NewSubKey는 RegistrySubKey 매개 변수를 통해 유효한 IRegistryKey 포인터를 출력하는 데 호출이 성공적이면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 메서드는 적절한 오류 코드를 반환합니다.

설명

메서드는 NewSubKey 지정된 레지스트리 키가 이미 있는 경우 열거나, 없는 경우 레지스트리에 새 키를 만듭니다. 메서드는 RegistrySubKey 매개 변수를 통해 새 키의 IRegistryKey 인터페이스에 대한 포인터를 출력합니다. 또한 메서드는 선택적 Disposition 매개 변수를 통해 상태 값을 출력하여 키가 열렸는지 생성되었는지 여부를 나타냅니다.

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

DesiredAccess 매개 변수는 RegistrySubKey 개체를 통해 액세스할 때 호출자가 하위 키에 필요한 액세스 제어 유형을 지정하는 액세스 제어 마스크입니다. 이 마스크는 레지스트리 하위 키에 대한 사용자의 액세스를 제어하는 ACL(액세스 제어 목록)과 혼동해서는 안 됩니다. PcNewRegistryKey 함수 또는 IPort::NewRegistryKey 메서드가 GeneralRegistryKey 형식의 레지스트리 키를 만드는 경우 ObjectAttributes 매개 변수는 ACL을 포함하는 보안 설명자를 포함하여 키의 특성을 지정합니다. 그러나 메서드가 NewSubKey 새 레지스트리 하위 키를 만들 때 해당 하위 키는 단순히 부모 키에서 ACL을 상속합니다. 메서드는 NewSubKey 부모 키와 다른 ACL을 지정하는 수단을 제공하지 않습니다.

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